Swisscom Sign Integration API

{"openapi":"3.1.0","info":{"title":"Swisscom Sign Integration API","description":"# Purpose\n\nThe Swisscom Sign *Integration API* enables backend systems to create, configure, release, and monitor digital signing processes end-to-end with minimal manual interaction.\n\n**Designed for** system-to-system integrations: line-of-business applications, backend services, and automated jobs.\n\n# Main Capabilities & Flow\n\n| Action | Endpoint |\n|--------|----------|\n| Create a process | `POST /api/process` |\n| Find all processes | `GET /api/process` |\n| Retrieve process details | `GET /api/process/{processId}` |\n| Attach documents | `POST /api/process/{processId}/attach` |\n| Release process (non-interactive) | `POST /api/process/{processId}/release` |\n| Handover to UI for completion | `POST /api/process/{processId}/setup` |\n| Monitor progress | `GET /api/process/{processId}/status` |\n| Retrieve signing record | `GET /api/process/{processId}/record` |\n| Download documents (Base64 JSON) | `GET /api/process/{processId}/file/{fileId}` |\n| Download document content (binary) | `GET /api/process/{processId}/file/{fileId}/content` |\n| Generate user-specific redirect URL | `POST /api/process/{processId}/open/{personId}` |\n\n# Samples\n\nRequest examples on the endpoints are only provided where a sample deviates from the standard flow (Sample 1).\n\n| # | Scenario | Key Feature |\n|---|----------|-------------|\n| 1 | Standard invite | Invite signer via deep link, release via API |\n| 2 | Invite with GwG identification | Online identification (GwG) before QES signing |\n| 3 | Delegated signing | System acts on behalf of user, user signs |\n| 4 | Draft with UI setup | Create draft, finalize in Swisscom Sign UI |\n| 5 | One-shot signing (OSS) | Single signer with on-the-fly authentication |\n\n<details>\n<summary><strong>Sample 1</strong> – Standard invite</summary>\n\n**Summary**\n\nStart a signing process programmatically and invite a person to sign.\n\n**Description**\n\nA backend system creates a new signing process and defines a single signer (invitee). The invitee receives a personalized deep link to complete the signing in Swisscom Sign. This is the most common integration pattern\nfor automated business workflows.\n\n**Typical flow**\n\n1. `POST /api/process` → create process\n2. `POST /api/process/{processId}/attach` → attach document\n3. `POST /api/process/{processId}/release` → release process\n4. `POST /api/process/{processId}/open/{personId}` → generate redirect URL for invitee\n\n</details>\n\n<details>\n<summary><strong>Sample 2</strong> – Invite with GwG identification</summary>\n\n**Summary**\n\nStart a GwG-compliant signing process with mandatory online identification.\n\n**Description**\n\nThe signer must complete online identification (GwG) before signing. Upon successful identification, the entire process is signed in a GwG-compliant manner. If identification is rejected, signing cannot proceed. Identification results are exposed read-only via the API.\n\n**Typical flow**\n\n1. `POST /api/process` → create process (with verification on signer)\n2. `POST /api/process/{processId}/attach` → attach document\n3. `POST /api/process/{processId}/release` → release process\n4. `POST /api/process/{processId}/open/{personId}` → generate redirect URL for invitee\n\n</details>\n\n<details>\n<summary><strong>Sample 3</strong> – Delegated signing</summary>\n\n**Summary**\n\nCreate a signing process on behalf of another user who becomes the signer.\n\n**Description**\n\nA system or representative (e.g., service desk) initiates a process on behalf of a user. The initiator acts as delegate, while the end user signs. Common in enterprise integrations where the application acts for the employee but the signature must come from the individual.\n\n**Typical flow**\n\n1. `POST /api/process` → create process (with initiator set to delegated user)\n2. `POST /api/process/{processId}/attach` → attach document(s)\n3. `POST /api/process/{processId}/release` → release process\n4. `POST /api/process/{processId}/open/{personId}` → generate redirect URL for signer\n\n</details>\n\n<details>\n<summary><strong>Sample 4</strong> – Draft with UI setup</summary>\n\n**Summary**\n\nCreate a draft process and modify it before release.\n\n**Description**\n\nA process is created in draft mode without immediate release. Documents can be attached or replaced, signer details updated, or properties modified before finalizing. Useful when human validation or business logic must occur before release.\n\n**Typical flow**\n\n1. `POST /api/process` → create draft\n2. `POST /api/process/{processId}/attach` → attach document(s)\n3. `POST /api/process/{processId}/setup` → finalize process\n\n</details>\n\n<details>\n<summary><strong>Sample 5</strong> – One-shot signing (OSS) for a single signer</summary>\n\n**Summary**\n\nRelease a process that uses One-Shot Signing (OSS) so the signer completes the signature in a single step without a pre-registered authentication device.\n\n**Description**\n\nOSS (One-Shot Signing) allows a signer to complete an advanced or qualified electronic signature without prior device registration (no Mobile ID app, no SMS OTP, no Passkey). The signer authenticates on-the-fly during the signing ceremony. This is ideal for one-time or infrequent signers. OSS is supported for `ADVANCED`, `ADVANCED_EU`, `QUALIFIED`, and `QUALIFIED_EU` signature levels.\n\nTo use OSS, pass `signatureMethods: [\"OSS\"]` in the release request. If multiple methods are provided alongside OSS, the signer can choose between them.\n\n**Typical flow**\n\nSteps 1, 2 and 4 are identical to Sample 1 — only the release request differs.\n\n1. `POST /api/process` → create process with a single signer\n2. `POST /api/process/{processId}/attach` → attach document\n3. `POST /api/process/{processId}/release` → release with `{ \"notification\": { \"locale\": \"de-CH\" }, \"signatureMethods\": [\"OSS\"] }`\n4. `POST /api/process/{processId}/open/{personId}` → generate redirect URL for signer\n\n</details>\n\n\n# Authentication & Authorization\n\nAll API access requires a **Bearer token** obtained via **OAuth 2.0 Client Credentials**.\n\n**Scopes**\n\n| Scope | Description |\n|-------|-------------|\n| `sswp:process:create` | Create and release processes |\n| `sswp:process:read` | Read own processes, status, records, files |\n| `sswp:process:read:all` | Read all processes (included for Organizations, on request for Corporates) |\n\n**Client Types**\n\n| Type | Issued by | Access | `read:all` |\n|------|-----------|--------|------------|\n| **Organization** | Self-service | Own organization | ✅ Included |\n| **Corporate** | Provider | Entire tenant | ⚠️ On request |\n\nAccess is restricted by the optional `organization_id` token claim. If present, access is limited to that organization.\n\n<details>\n<summary><strong>Token example</strong></summary>\n\n```json\n{\n  \"iss\": \"https://iam.example.com/\",\n  \"sub\": \"client-123\",\n  \"aud\": \"swisscom-sign-system-api\",\n  \"scope\": \"sswp:process:create sswp:process:read\",\n  \"organization_id\": \"7f0b2f2a-1e6e-4b30-9f0c-1c9a9b3d1234\",\n  \"exp\": 1735660800,\n  \"iat\": 1735657200\n}\n```\n\n</details>\n\n\n# API Conventions\n\n| Aspect | Convention |\n|--------|------------|\n| **Content-Type** | `application/json` (files as Base64-encoded strings); `GET .../file/{fileId}/content` returns raw binary (`application/pdf` or `application/zip`) |\n| **Timestamps** | ISO-8601 with offset (`2026-03-12T14:30:00+01:00`) |\n| **IDs** | UUIDs, stable and reusable across requests |\n| **Pagination** | Query params: `page`, `size`, `sort` |\n\n**HTTP Status Codes**\n\n| Code | Meaning |\n|------|---------|\n| `200` | Success |\n| `201` | Created |\n| `208` | Already reported (idempotent create) |\n| `400` | Bad request (validation error) |\n| `401` | Unauthorized (invalid/missing token) |\n| `403` | Forbidden (insufficient scope) |\n| `404` | Resource not found |\n| `409` | Conflict (e.g., process already released) |\n\n# Versioning & Compatibility\n\n## Versioning Scheme\n\nThis API follows **Semantic Versioning** (MAJOR.MINOR.PATCH):\n\n| Change Type | Version Impact | Example |\n|-------------|----------------|---------|\n| Breaking changes | MAJOR ↑ | `2.0.0` → `3.0.0` |\n| New features (backward-compatible) | MINOR ↑ | `2.11.0` → `2.12.0` |\n| Bug fixes | PATCH ↑ | `2.12.0` → `2.12.1` |\n\n## Deprecation Policy\n\n- Deprecated fields remain functional for **at least 2 minor versions**\n- Deprecated features are marked with `⚠️ Deprecated` in the schema documentation\n- Migration guidance is provided in the changelog\n\n## API Versions\n\n| Version | Status       |\n|--------|--------------|\n| `v2` | `✅ Current`|\n| `v1` | `⚠️ Deprecated`|\n  \n**⚠️ Migration Notice**\n\nThe `v1` API is **deprecated** and will reach end of life.\nPlease migrate to the `v2` API. **New credentials are required**.\n\n\n## Change Log\n\n<details>\n<summary><strong>2.19.0</strong> – Binary file download, signature methods & OSS sample</summary>\n\n**✨ New Features**\n- **Binary file download**: New `GET /api/process/{processId}/file/{fileId}/content` endpoint returns the raw binary content of a process file instead of a Base64-encoded JSON document\n  - The `Content-Type` reflects the actual file type: `application/pdf` for documents, `application/zip` for verification documents\n  - The response includes a `Content-Disposition` header with the original filename\n  - Authorization and error semantics are identical to the existing `GET /api/process/{processId}/file/{fileId}` endpoint, which remains unchanged\n- **Signature methods**: Release endpoint now accepts optional `signatureMethods` to restrict allowed methods (`APP`, `CLICK`, `OSS`, `PASSKEY`, `SMS`) per process. Methods are validated against the document's signature level.\n- **New signature methods**: Added `PASSKEY` (WebAuthn passkey authentication) and `OSS` (One-Shot Signing without prior device registration), both for corporate tenants only\n- **Sample 5 (OSS)**: New integration sample demonstrating One-Shot Signing for a single signer without prior device registration\n\n**📖 Documentation**\n- **SignatureMethod descriptions**: Each signature method now includes a detailed description in the schema documentation\n\n</details>\n\n<details>\n<summary><strong>2.18.0</strong> – Stable pagination response</summary>\n\n**🔄 Changed**\n- **Process listing**: `GET /api/process` now returns a stable `page` object with `totalElements`, `totalPages`, `size`, and `number`\n\n**⚠️ Deprecated**\n- Root-level fields `totalElements`, `totalPages`, `number`, `size`, `first`, `last` → migrate to `page.totalElements`, `page.totalPages`, `page.number`, `page.size`\n\n</details>\n\n<details>\n<summary><strong>2.17.0</strong> – Automatic Reminders</summary>\n\n**✨ New Features**\n- **Reminders**: Release endpoint now allows an optional configuration of automatic reminders in the `notification` node.\n- **Reminders**: There are two ways to define reminders, and they can be used independently of each other or even combined:\n    - `interval` – Define a fixed interval, at which the reminders will be sent.\n    - `beforeExpiry` – Define a list of durations to send reminders a certain amount of time before the expiration date.\n</details>\n\n<details>\n<summary><strong>2.16.0</strong> – Prevent Organization clients from using GWG</summary>\n\n**⚠️ Breaking Changes**\n- **GWG**: Prevent clients of type `Organization` from creating processes that would use the `GWG` flow.\n</details>\n\n<details>\n<summary><strong>2.15.0</strong> – Tag-based signature positioning</summary>\n\n**✨ New Features**\n- **Tag-based signature positioning**: Attach endpoint now accepts `\"locator\": \"TAG\"` on signature positions to resolve placement at runtime by searching for a tag string embedded in the PDF (e.g. `\\s1\\` for the first signer, `\\s2\\` for the second, etc.)\n- The tag marks the upper-left corner of the visual signature field\n- Optional `offsetX` / `offsetY` (PDF points, range −200 to 200) allow fine-tuning the position relative to the tag\n- Coordinates (`positionX`, `positionY`, `pageNumber`) are not required when `locator` is `TAG`\n- Default behaviour (omitting `locator` or using `\"locator\": \"COORDINATES\"`) is fully backward-compatible\n\n</details>\n\n<details>\n<summary><strong>2.14.0</strong> – Process listing filters</summary>\n\n**✨ New Features**\n- **Process listing**: Added optional `teamId` filter parameter to `GET /api/process` for filtering processes by team\n- **Process listing**: Added optional `validUntilWithin` filter parameter (ISO 8601 duration, e.g. `P30D`) to `GET /api/process` for filtering processes whose `validUntil` falls within the given duration\n\n\n</details>\n\n<details>\n<summary><strong>2.13.0</strong> – Extended signer statuses</summary>\n\n**✨ New Features**\n- **Signer status**: Added new status values to `SignerStatus`:\n  - `WAITING` – Signer has not been invited to the process yet\n  - `DECLINED` – Signer has declined the signature process\n  - `REMOVED` – Signer has been removed from the signature process\n  - `REPLACED` – Signer has been replaced with a new signer\n\n</details>\n\n<details>\n<summary><strong>2.12.0</strong> – Process expiration & notification settings</summary>\n\n**✨ New Features**\n- **Process expiration**: Release endpoint now accepts optional `validUntil` to set process expiration date\n\n**🔄 Changed**\n- **Notification settings**: Introduced new `notification` object with:\n  - `locale` – language for notifications\n  - `suppress` – opt-out control for notification types (`INVITE`, `COMPLETION`, `ALL`)\n\n**⚠️ Deprecated**\n- `language` field on Release request → use `notification.locale` instead\n\n</details>\n\n<details>\n<summary><strong>2.11.0</strong> – Process listing</summary>\n\n**✨ New Features**\n- **Process listing**: New `GET /api/process` endpoint with:\n  - Filter by `status`\n  - Sort by `createdDate`\n  - Pagination support\n\n</details>\n\n<details>\n<summary><strong>2.10.0</strong> – Signer status rename</summary>\n\n**🔄 Changed**\n- **Signer status**: Renamed status value `DISCONTINUED` → `CANCELED` for clarity\n- **Timestamp field**: New attribute `canceledOn` replaces `discontinuedOn`\n\n**⚠️ Deprecated**\n- `discontinuedOn` → use `canceledOn` instead\n\n</details>\n\n<details>\n<summary><strong>2.9.0</strong> – Team support</summary>\n\n**✨ New Features**\n- Added optional `teamId` on `Process` for team-based organization\n\n</details>\n\n<details>\n<summary><strong>2.8.0</strong> – Partner tracking</summary>\n\n**✨ New Features**\n- Added optional `partnerId` on `Process` for partner management and tracking\n\n</details>\n\n<details>\n<summary><strong>2.7.0</strong> – Authorization options</summary>\n\n**✨ New Features**\n- Added optional `authorization` on `Process` (write-only)\n- Default: `CODE` for backwards-compatibility\n\n</details>\n\n<details>\n<summary><strong>2.6.0</strong> – Verification cleanup</summary>\n\n**🗑️ Removed**\n- Removed `domicile` on `Verification`\n\n</details>\n\n<details>\n<summary><strong>2.5.0</strong> – Custom signature stickers</summary>\n\n**✨ New Features**\n- **Signature sticker rendering**: New field `stickerProvider` on `FileSignaturePosition`\n  - `VISUAL_SIGNATURE_PROVIDER` – classic rendering (default)\n  - `CUSTOM_VISUAL_SIGNATURE_PROVIDER` – user-drawn signature support\n\n</details>\n\n<details>\n<summary><strong>2.4.0</strong> – Validation improvements</summary>\n\n**🔒 Validation**\n- Email length restricted to max `254` characters\n- `externalIdentifier` character set restricted for URL-encoding conformity\n\n</details>\n\n<details>\n<summary><strong>2.3.0</strong> – Authentication rename</summary>\n\n**🔄 Renamed**\n- `pairing` → `authentication`\n- `pairing.userId` → `authentication.identity`\n- `pairing.app` → `authentication.namespace`\n\n</details>\n\n<details>\n<summary><strong>2.2.0</strong> – Mandatory fields & scope/mode</summary>\n\n**✨ New Features**\n- Added `scope` and `mode` to Setup and Open requests\n- Process creation now returns full `Process` schema\n\n**⚠️ Breaking Changes**\n- `Signer.firstName` and `Signer.lastName` are now **mandatory**\n- `NonPerson.name` is now **mandatory**\n- Process-wide `email` validation on `Participants`\n\n**🐛 Bug Fixes**\n- Fixed: `externalIdentifier` was not accepted in Open request\n\n</details>\n\n<details>\n<summary><strong>2.1.0</strong> – Signer status fields</summary>\n\n**✨ New Features**\n- Added to `Signer` schema:\n  - `status` – current signer state\n  - `signedOn` – signature timestamp\n  - `discontinuedOn` – cancellation timestamp\n\n</details>\n\n<details>\n<summary><strong>2.0.0</strong> – Major release</summary>\n\n**🚀 Major Release**\n- Complete REST API refactoring\n\n</details>\n","termsOfService":"https://sign.swisscom.ch/api-docs","contact":{"name":"Support","url":"https://digitaltrust.swisscom.ch/en/"},"version":"2.19.0","x-changelog":{"2.19.0":"New `GET /api/process/{processId}/file/{fileId}/content` endpoint returns the raw binary content of a process file instead of a Base64-encoded JSON document. The `Content-Type` reflects the actual file type (`application/pdf` for documents, `application/zip` for verification documents). The response includes a `Content-Disposition` header with the original filename. Authorization and error semantics are identical to the existing file endpoint, which remains unchanged. Release endpoint now accepts optional `signatureMethods` to restrict the allowed signature methods (`APP`, `CLICK`, `OSS`, `PASSKEY`, `SMS`) per process. Methods are validated against the document's signature level. Added the two new signature methods `PASSKEY` (WebAuthn passkey authentication) and `OSS` (One-Shot Signing without prior device registration), both for corporate tenants only. Added Sample 5 (OSS single signer). Enhanced `signatureMethods` documentation with detailed descriptions for each method.","2.18.0":"The `GET /api/process` response now includes a stable `page` object containing `totalElements`, `totalPages`, `size`, and `number`. The root-level fields `totalElements`, `totalPages`, `number`, `size`, `first`, and `last` are deprecated and will be removed in a future version. Please migrate to `page.totalElements`, `page.totalPages`, `page.size`, and `page.number`.","2.17.0":"Release endpoint now allows an optional configuration of automatic reminders in the `notification` node. Reminders can be defined with an `interval` or `beforeExpiry` configuration.","2.16.0":"GwG online identity verification (`signer.verification`) is now restricted to corporate tenants. Submitting a `verification` object on a signer for a non-corporate tenant will be rejected with a `400 Bad Request` validation error.","2.15.0":"Attach endpoint now accepts `locator: TAG` on signature positions to resolve placement at runtime by searching for a tag string embedded in the PDF (`\\s1\\` for index 0, `\\s2\\` for index 1, etc.). The tag marks the upper-left corner of the signature field. Optional `offsetX` / `offsetY` (PDF points, −200 to 200) allow fine-tuning. Coordinates are not required when using TAG. Default behaviour (omitting `locator` or using COORDINATES) is fully backward-compatible.","2.14.0":"Added optional `teamId` filter parameter to `GET /api/process` for filtering processes by team. Added optional `validUntilWithin` filter parameter (ISO 8601 duration) to `GET /api/process` for filtering processes whose `validUntil` falls within the given duration.","2.13.0":"Added new signer status values: `WAITING` (not yet invited), `DECLINED` (signer declined), `REMOVED` (signer removed), and `REPLACED` (signer replaced with a new signer).","2.12.0":"Release endpoint now accepts optional `validUntil` to set process expiration. Replaced `language` field with new `notification` object containing `locale` and `suppress` for opt-out control of notification types (`INVITE`, `COMPLETION`, `ALL`). The `language` field is now deprecated.","2.11.0":"New findAll service added for processes with filter (`status`), sorting (`createdDate`), and paging.","2.10.0":"Signer.status has been renamed from `DISCONTINUED` to `CANCELED` for better clarity. New attribute `canceledOn` replaces `discontinuedOn`, which has been set to deprecated.","2.9.0":"Added optional `teamId` on `Process`.","2.8.0":"Added optional `partnerId` to `Process` for enhanced partner management and tracking.","2.7.0":"Added optional `authorization` on `Process` as write-only. Defaults to CODE for backwards-compatability when no authorization value is provided.","2.6.0":"Removed `domicile` on `Verification`.","2.5.0":"Added new field `stickerProvider` to `FileSignaturePosition`. This new field determines how signature stickers are rendered. Currently, two choices are available, the classic `VISUAL_SIGNATURE_PROVIDER` for backwards-compatibility, and a new `CUSTOM_VISUAL_SIGNATURE_PROVIDER`. If `CUSTOM_VISUAL_SIGNATURE_PROVIDER` is selected, users can manually draw a signature, which will be incorporated into the sticker.","2.4.0":"Restricted email length to `254` characters. Restricted `externalIdentifier` characters to strengthen url-encoding conformity.","2.3.0":"Renamed `pairing` and its fields `pairing.userId` and `pairing.app` to `authentication`, `authentication.identity` and `authentication.namespace`.","2.2.0":"- Added `scope` and `mode` to Setup and Open requests.\n- `Signer.firstName` and `Signer.lastName` are now mandatory.\n- `NonPerson.name` is now mandatory.\n- Added process wide `email` validation on `Participants`.\n- Process creation now returns `Process` scheme.\n- Fixed a bug where the `externalIdentifier` was not accepted in the Open request.\n","2.1.0":"Added `signer.status`, `signer.signedOn` and `signer.discontinuedOn` to `Signer` schema.","2.0.0":"Major refactoring of the REST API. The API is now structured around a single `/processes` endpoint, which allows for more flexible and efficient process management. "},"x-last-updated":{"last-updated":"2026-07-16"}},"externalDocs":{"description":"Service description","url":"https://www.swisscom.ch/sign"},"servers":[{"url":"https://sign.swisscom.ch/system","description":"Productive Server"}],"security":[{"SwisscomSignOAuth2":[]}],"tags":[{"name":"Process: create","description":"Allows you to set up your process according to your needs, including adding documents, configuring invitees, setting signature options, and submitting the process for execution."},{"name":"Process: read","description":"Access process information and download signed or original documents once the signing is complete."}],"paths":{"/api/process":{"get":{"tags":["Process: read"],"summary":"Get all processes (paginated)","description":"Returns a paginated list of processes.\n\nSupports optional filtering by `status`, `teamId`, and `validUntilWithin` (ISO 8601 duration).\nThe page size is limited to a maximum of 20 items.\nSorting is strictly performed on 'createdDate', but the direction (ASC/DESC) can be defined.\n","operationId":"findAll","parameters":[{"name":"status","in":"query","description":"Filter by status.","required":false,"schema":{"type":"string","description":"Lifecycle states:\n* `CREATED` – Process object exists; configuration may continue.\n* `PENDING` – Process released; waiting for signatures..\n* `COMPLETED` – All required signatures done.\n* `EXPIRED` – Automatically set when `validUntil` is reached.\n","enum":["CREATED","PENDING","COMPLETED","EXPIRED"],"example":"PENDING"},"example":"PENDING"},{"name":"teamId","in":"query","description":"Filter by team ID.","required":false,"schema":{"type":"string","format":"uuid"},"example":"6f1a5c4d-2d9a-4f12-a1c5-bc6e2bcb2d6a"},{"name":"validUntilWithin","in":"query","description":"Filter by validUntil within the given ISO 8601 duration (e.g. P30D, PT12H).","required":false,"schema":{"type":"string"},"example":"P30D"},{"name":"page","in":"query","description":"Zero-based page index (0..N)","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"size","in":"query","description":"The size of the page to be returned","required":false,"schema":{"type":"integer","default":20,"minimum":1}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","required":false,"schema":{"type":"array","default":["createdDate,DESC"],"items":{"type":"string"}}}],"responses":{"200":{"description":"Returns a page of processes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessPage"}}}},"400":{"description":"Invalid pagination parameters (e.g. size > 20) or invalid sort direction."},"401":{"description":"Authorization information is missing or invalid."}},"security":[{"SwisscomSignOAuth2":["sswp:process:read:all"]}]},"post":{"tags":["Process: create"],"summary":"Create a process","description":"Creates a new signing process.\n- Non-interactive (API release): Provide all required data (documents, signers, options) up front.\n- Setup (handover to Swisscom Sign UI): You can submit a minimal process and adjust metadata later in the UI.\n","operationId":"create","requestBody":{"description":"Minimal payload for creating a signing process.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Process"},"examples":{"(1) Standard invite":{"description":"(1) Standard invite","value":{"signatureLevel":"SIMPLE","initiator":{"type":"NON_PERSON","externalIdentifier":"ext-systems_oms-42","name":"Swisscom Sign Orchestrator"},"invitees":{"signers":[{"type":"SIGNER","externalIdentifier":"crm-4711","firstName":"John","lastName":"Doe","email":"john.doe@example.com"}]}}},"(2) Invite with GwG identification (Corporate only)":{"description":"(2) Invite with GwG identification (Corporate only)","value":{"signatureLevel":"QUALIFIED","initiator":{"type":"NON_PERSON","externalIdentifier":"ext-systems_oms-42","name":"Swisscom Sign Orchestrator"},"invitees":{"signers":[{"type":"SIGNER","externalIdentifier":"crm-4711","firstName":"John","lastName":"Doe","email":"john.doe@example.com","verification":{"residentPermit":true}}]}}},"(3) Delegated signing":{"description":"(3) Delegated signing","value":{"signatureLevel":"SIMPLE","initiator":{"type":"SIGNER","externalIdentifier":"crm-4711","firstName":"John","lastName":"Doe","email":"john.doe@example.com"}}},"(4) Draft with UI setup":{"description":"(4) Draft with UI setup","value":{"signatureLevel":"SIMPLE","initiator":{"type":"PERSON","externalIdentifier":"crm-4711"}}}}}},"required":true},"responses":{"201":{"description":"The process was created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Process"}}}},"401":{"description":"Authorization information is missing or invalid."},"409":{"description":"Occurs when there is a general error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"SwisscomSignOAuth2":["sswp:process:create"]}]}},"/api/process/{processId}/setup":{"post":{"tags":["Process: create"],"summary":"Finalize process in Swisscom Sign UI","description":"Launches the Swisscom Sign web interface for the initiator to complete the process setup.\nThis includes defining visual elements and participant data.\n\nOnce setup is complete, the process is automatically released and notifications are handled by Swisscom Sign.\n\n**Preconditions:**\n- A process was created via `/process`.\n- The process has not yet been released.\n","operationId":"setup","parameters":[{"name":"processId","in":"path","description":"Unique identifier of the process to finalize via UI.","required":true,"schema":{"type":"string","format":"uuid"},"example":"6f1a5c4d-2d9a-4f12-a1c5-bc6e2bcb2d6a"}],"requestBody":{"description":"Defines how the Swisscom Sign UI should behave when the process is opened for setup.\nTypical use cases:\n- Control the language of the UI.\n- Configure redirect URLs (back, success).\n- Provide pairing information (App-only, temporary).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessSetupRequest"},"examples":{"(4) Draft with UI setup":{"description":"(4) Draft with UI setup","value":{"language":"en-GB"}}}}},"required":true},"responses":{"202":{"description":"The setup request has been accepted. Please redirect to the provided URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessSetupResponse"}}}},"401":{"description":"Authorization information is missing or invalid."},"409":{"description":"Occurs when there is a general error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"SwisscomSignOAuth2":["sswp:process:create"]}]}},"/api/process/{processId}/release":{"post":{"tags":["Process: create"],"summary":"Release process and notify participants","description":"Releases a previously created and fully configured process. Personal access URLs are returned for each participant.\nThese can be used for asynchronous execution, typically via email.\n\nOptionally, you may include email parameters to notify participants directly.\nOptionally, you may configure automatic reminder emails for pending participants.\nOptionally, you may restrict the allowed signature methods (`APP`, `CLICK`, `OSS`, `PASSKEY`, `SMS`) via `signatureMethods`.\nIf omitted, the tenant defaults apply. Methods are validated against the document's signature level.\n\nPreconditions:\n- A process was created via `/process` with at least one participant.\n- At least one document was attached using `/process/{processId}/attach`.\n- Every signer must be placed on at least one document.\n- At least one document must have all signers placed on it.\n- All visual signatures are placed within the visible area.\n","operationId":"release","parameters":[{"name":"processId","in":"path","description":"Unique identifier of the process to be released.","required":true,"schema":{"type":"string","format":"uuid"},"example":"6f1a5c4d-2d9a-4f12-a1c5-bc6e2bcb2d6a"}],"requestBody":{"description":"Optional notification and reminder configuration for participants.\n\n**Notification behavior:**\n- No body or empty body → no notifications sent\n- `notification.locale` set → all participants notified in that language\n- `notification.suppress` set → opt-out specific notification types\n\n**Automatic reminders (`notification.reminder`):**\n- `reminder.interval` → recurring reminder every X days while the process is pending (e.g. `P3D`)\n- `reminder.beforeExpiry` → one reminder per entry, sent X days before `validUntil` (e.g. `[\"P7D\", \"P2D\"]`)\n- Both fields are optional and independent; omit `reminder` entirely to disable automatic reminders\n- Requires `notification.locale` — reminders cannot be sent without a notification locale\n- Incompatible with `notification.suppress: [\"ALL\"]` → returns 409\n\n**Deprecated:** The `language` field is deprecated. Use `notification.locale` instead.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessReleaseRequest"},"examples":{"(1a) Standard invite (emails in German)":{"description":"(1a) Standard invite (emails in German)","value":{"notification":{"locale":"de-CH"}}},"(1b) Standard invite (no emails)":{"description":"(1b) Standard invite (no emails)","value":{"notification":{"locale":"de-CH","suppress":["ALL"]}}},"(2) Invite with GwG identification (emails in German)":{"description":"(2) Invite with GwG identification (emails in German)","value":{"notification":{"locale":"de-CH"}}},"(3) Delegated signing (emails in German)":{"description":"(3) Delegated signing (emails in German)","value":{"notification":{"locale":"de-CH"}}},"(4a) Invite with automatic reminders (before expiry)":{"description":"Sends a reminder 7 days and again 2 days before the process expires.","value":{"validUntil":"2026-12-31T23:59:59+01:00","notification":{"locale":"de-CH","reminder":{"beforeExpiry":["P7D","P2D"]}}}},"(4b) Invite with automatic reminders (recurring interval)":{"description":"Sends a recurring reminder every 3 days while the process is pending.","value":{"validUntil":"2026-12-31T23:59:59+01:00","notification":{"locale":"de-CH","reminder":{"interval":"P3D"}}}},"(4c) Invite with automatic reminders (combined)":{"description":"Recurring reminder every 3 days, plus dedicated reminder

# --- truncated at 32 KB (203 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/swisscom/refs/heads/main/openapi/swisscom-sign-integration-api-openapi.json