Swisscom Process: read API

openapi: 3.2.0
info:
  title: 'Swisscom Sign Integration Process: read 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**\U0001F4D6 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**\U0001F504 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**\U0001F504 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**\U0001F504 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**\U0001F5D1️ 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**\U0001F512 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**\U0001F504 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**\U0001F41B 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**\U0001F680 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.

      - `Signer.firstName` and `Signer.lastName` are now mandatory.

      - `NonPerson.name` is now mandatory.

      - Added process wide `email` validation on `Participants`.

      - Process creation now returns `Process` scheme.

      - Fixed a bug where the `externalIdentifier` was not accepted in the Open request.

      '
    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'
servers:
- url: https://sign.swisscom.ch/system
  description: Productive Server
security:
- SwisscomSignOAuth2: []
tags:
- 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.


        Supports optional filtering by `status`, `teamId`, and `validUntilWithin` (ISO 8601 duration).

        The page size is limited to a maximum of 20 items.

        Sorting is strictly performed on ''createdDate'', but the direction (ASC/DESC) can be defined.

        '
      operationId: findAll
      parameters:
      - name: status
        in: query
        description: Filter by status.
        required: false
        schema:
          type: string
          description: 'Lifecycle states:

            * `CREATED` – Process object exists; configuration may continue.

            * `PENDING` – Process released; waiting for signatures..

            * `COMPLETED` – All required signatures done.

            * `EXPIRED` – Automatically set when `validUntil` is reached.

            '
          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
  /api/process/{processId}/open/{personId}:
    post:
      tags:
      - 'Process: read'
      summary: Generate participant access URL
      description: 'Generate an URL for a specific participant that can be used to open the process in the Swisscom Sign UI. Optional return URLs can be used to redirect the user back to the calling third party system. If an unreleased process is opened, an error is returned. For unreleased processes, /process/{processId}/setup can be used.


        Preconditions:

        * The service can only be used if the process has already been released via /processId/{processId}/release.'
      operationId: open
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: personId
        in: path
        description: The system-assigned identifier or the external reference from your system can be used to identify the person.
        required: true
        schema:
          type: string
          description: The system-assigned identifier or the external reference from your system can be used to identify the person.
      requestBody:
        description: 'Defines how the Swisscom Sign UI should behave when the process is opened for a person.

          Typical use cases:

          - Control the language of the UI.

          - Configure redirect URLs (back, success).

          - Skip authorization for trusted environments.

          - Provide pairing information (App-only, temporary).

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessOpenRequest'
            examples:
              (1) Standard invite (suppress authorization):
                description: (1) Standard invite (suppress authorization)
                value:
                  language: en-GB
                  skipAuthorization: true
              (3) Delegated signing (with authorization):
                description: (3) Delegated signing (with authorization)
                value:
                  language: en-GB
                  skipAuthorization: false
        required: true
      responses:
        '200':
          description: You receive an URL specific to the subscriber with a defined validity period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessOpenResponse'
        '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:read
  /api/process/{processId}:
    get:
      tags:
      - 'Process: read'
      summary: Get process details
      description: 'Returns the full process object including participants, documents, properties,

        and current status.


        Can only be accessed if the process has been initiated and the caller is authorized.

        '
      operationId: getProcess
      parameters:
      - name: processId
        in: path
        description: Unique identifier of the process.
        required: true
        schema:
          type: string
          format: uuid
        example: 6f1a5c4d-2d9a-4f12-a1c5-bc6e2bcb2d6a
      responses:
        '200':
          description: Returns the full document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '401':
          description: Authorization information is missing or invalid.
        '404':
          description: Process not found.
        '409':
          description: Occurs when there is a general error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - SwisscomSignOAuth2:
        - sswp:process:read
  /api/process/{processId}/status:
    get:
      tags:
      - 'Process: read'
      summary: Get process status
      description: Returns the current status of the process. Requires that the process exists and the caller is authorized.
      operationId: getStatus
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Returns the state of the desired document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessStatusResponse'
        '401':
          description: Authorization information is missing or invalid.
        '404':
          description: Process not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Occurs when there is a general error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - SwisscomSignOAuth2:
        - sswp:process:read
  /api/process/{processId}/record:
    get:
      tags:
      - 'Process: read'
      summary: Get auditing records
      description: This service can be used only with a valid process. All created auditing records are returned in descending order of creation date. Thus, the first record is the most recent.
      operationId: getRecords
      parameters:
      - name: processId
        in: path
        description: Unique identifier of the process.
        required: true
        schema:
          type: string
          format: uuid
        example: 6f1a5c4d-2d9a-4f12-a1c5-bc6e2bcb2d6a
      responses:
        '200':
          description: Returns a list of auditing records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditSuccessRecordResponse'
        '401':
          description: Authorization information is missing or invalid.
        '409':
          description: Occurs when there is a general error or the process is missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - SwisscomSignOAuth2:
        - sswp:process:read
  /api/process/{processId}/file/{fileId}:
    get:
      tags:
      - 'Process: read'
      summary: Download process file
      description: 'Retrieves a file that belongs to the specified process.


        Possible file types:

        - Attached original documents

        - Signed or partially signed documents (available as soon as at least one signer has signed)

        - Verification documents (if online verification was performed)


        Files are only available until the process has been archived (archivedOn is set).

        '
      operationId: getFile
      parameters:
      - name: processId
        in: path
        description: System-assigned process identifier (UUID).
        required: true


# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/swisscom/refs/heads/main/openapi/swisscom-process-read-api-openapi.yml