--- title: "Release process and notify participants" method: POST path: "/api/process/{processId}/release" tags: ["Process: create"] --- # Release process and notify participants `POST /api/process/{processId}/release` ## Request - Base URL: `https://sign.swisscom.ch/system` - URL: `https://sign.swisscom.ch/system/api/process/{processId}/release` - Auth: OAuth 2 - Client credentials - Token URL: `https://sign.swisscom.ch/realms/swisscom-public/protocol/openid-connect/token` scopes: `sswp:process:create` - TypeScript: (a function with typed inputs; its response is checked against the schema) Releases a previously created and fully configured process. Personal access URLs are returned for each participant. These can be used for asynchronous execution, typically via email. Optionally, you may include email parameters to notify participants directly. Optionally, you may configure automatic reminder emails for pending participants. Optionally, you may restrict the allowed signature methods (`APP`, `CLICK`, `OSS`, `PASSKEY`, `SMS`) via `signatureMethods`. If omitted, the tenant defaults apply. Methods are validated against the document's signature level. Optionally, you may opt signers into workflow actions (`DECLINE`, `DELEGATE`, `REMOVE`, `REPLACE`) via `signerCapabilities`. If omitted, no signer actions are permitted. These actions are only activated via this endpoint; they are executed via the Swisscom Sign UI, not directly through the API. Optionally, you may enforce a serial signing order via `signingOrder: SERIAL`, gated by each signer's `signingIndex` (set at creation). If omitted, defaults to `PARALLEL`. Preconditions: - A process was created via `/process` with at least one participant. - At least one document was attached using `/process/{processId}/attach`. - Every signer must be placed on at least one document. - At least one document must have all signers placed on it. - All visual signatures are placed within the visible area. ## Path parameters - `processId` string, uuid, required ## Request body - ProcessReleaseRequest: Optional configuration for the release operation. **Notification behavior:** - Empty body → no notifications sent (legacy behavior) - `language` set (deprecated) → all participants notified in that language - `notification` object present → explicit control via `locale` and `suppress` **Migration from `language` to `notification`:** ```json // Old (deprecated): { "language": "de-CH" } // New (recommended): { "notification": { "locale": "de-CH" } } // Suppress specific types: { "notification": { "locale": "de-CH", "suppress": ["INVITE"] } } // Suppress all notifications: { "notification": { "locale": "de-CH", "suppress": ["ALL"] } } ``` **Supported locales:** `en-GB`, `de-CH`, `fr-CH`, `it-CH` (BCP-47) - `validUntil` string, date-time: Expiration timestamp of the process. After this point in time, the system automatically transitions the process status to `EXPIRED`. If not provided, the valid until date is automatically set to 30 days in the future. - `language` string: **Deprecated:** Use `notification.locale` instead. Legacy behavior: Setting this field enables all notification types (`INVITE`, `COMPLETION`) for all participants in the specified language. If both `language` and `notification.locale` are provided, `notification.locale` takes precedence. Supported values: `en-GB`, `de-CH`, `fr-CH`, `it-CH` (BCP-47). - `notification` NotificationSettings: Controls email notification behavior for all participants. **Default behavior:** All notification types (`INVITE`, `COMPLETION`) are sent to all participants. **Opt-out:** Use `suppress` to disable specific types or `ALL` to disable all notifications. - `locale` 'en-GB' | 'de-CH' | 'fr-CH' | 'it-CH', required: Locale for all notification emails (BCP-47 format). - `suppress` string[]: Notification types to suppress (opt-out). - Omit or empty → all notifications sent - `["INVITE"]` → only `COMPLETION` sent - `["COMPLETION"]` → only `INVITE` sent - `["ALL"]` → no notifications sent - `reminder` ReminderSettings: Automatic reminder configuration for pending participants. - `interval` string: Interval between recurring reminders as ISO 8601 duration. Minimum: P1D, Maximum: P30D. - `beforeExpiry` string[]: One or more points in time before expiry at which to send a reminder, expressed as ISO 8601 durations. Each value must be between P1D and P30D. - `signatureMethods` string[], nullable: Optional list of allowed signature methods for this process. If not provided, the tenant defaults are used. **Available methods:** * `APP` – Mobile app-based authentication via Swisscom Mobile ID. * `CLICK` – Click-to-sign: the signer confirms by clicking, without further authentication (SES only). Identity assurance is based on the process access authorization (e.g. email or SMS). * `OSS` – One-Shot Signing: on-the-fly authentication without prior device registration. Ideal for one-time or infrequent signers. **Corporate tenants only.** * `PASSKEY` – WebAuthn passkey authentication. **Corporate tenants only.** * `SMS` – One-time password (OTP) delivered via SMS. **Compatibility with signature levels:** * `SIMPLE` → `CLICK` * `ADVANCED` → `APP`, `OSS`, `PASSKEY`, `SMS` * `ADVANCED_EU` → `APP`, `OSS`, `PASSKEY` * `QUALIFIED` / `QUALIFIED_EU` → `APP`, `OSS`, `PASSKEY` - `signingFeatures` string[], nullable: Optional set of opt-in signing features for this process. If not provided, the tenant defaults are used. **Available features:** * `SIGN_IDENT_DOCUMENT` – Document produced by online identification is co-signed within the process. - `signerCapabilities` string[], nullable: Opt-in signer actions permitted in the process. If not provided, no signer actions are permitted. **Available actions:** * `DECLINE` – Signer may decline signing. * `DELEGATE` – Signer may delegate to another person. * `REMOVE` – An invited signer may be removed. * `REPLACE` – An invited signer may be replaced. - `signingOrder` 'PARALLEL' | 'SERIAL', nullable: Signing order for the process. Defaults to `PARALLEL` if not provided. * `PARALLEL` – All signers may sign in any order. * `SERIAL` – Signers sign one after another, per each signer's `signingIndex` (missing `signingIndex` is treated as `0`; ties are broken by invitation order). ## Response `200` Process released; participant URLs returned (permanently valid). - ReleaseResponse: Response returned after successfully releasing a signing process. Contains the process identifier, its current lifecycle status, and participant-specific access URLs that can be used to redirect users to the signing UI. - `id` string, uuid: System-assigned identifier of the released process. - `status` 'CREATED' | 'PENDING' | 'COMPLETED' | 'EXPIRED': Lifecycle status after release. Typically `PENDING` (waiting for signatures). - `participants` ReleasedParticipant[]: List of participants with their personalized access URLs. Each participant receives a unique URL that can be used to redirect them to the Swisscom Sign UI for signing. URLs are permanent and do not expire. - `id` string, uuid: System-assigned identifier of the participant. - `externalIdentifier` string: External reference of the participant as provided by the client system. - `url` string: Permanent participant-specific URL to open the signing process. The link can be embedded in e-mails or client applications. When opened, the participant must still pass the regular authorization/identification flow in the process. One thing to note: If the process has been released with serial signing order, the participants can only access the process, once it is their turn to sign. This does not apply to the initiator, who always has access. ## Other responses - `208`: Process was already released; participant URLs returned (permanently valid). - `400`: Invalid request – the process ID is no UUID or the request body failed validation. - `401`: Authorization information is missing or invalid. - `403`: Forbidden – the token lacks the scope `sswp:process:create`. - `404`: Process not found, or it does not belong to the organization of the token. - `406`: Not acceptable – the process does not meet the requirements for the release, e.g. a signer without signature position. - `409`: Conflict – e.g. reminders configured but all notifications are suppressed. --- [API](https://skmtc.dev/swisscom/apis/swisscom-sign-integration-api.md) - [All operations](https://skmtc.dev/swisscom/apis/swisscom-sign-integration-api/llms.txt) - [OpenAPI document](https://skmtc.dev/swisscom/apis/swisscom-sign-integration-api/revisions/c7d25e820106?raw)