---
title: "Generate participant access URL"
method: POST
path: "/api/process/{processId}/open/{personId}"
tags: ["Process: read"]
---

# Generate participant access URL

`POST /api/process/{processId}/open/{personId}`

## Request

- Base URL: `https://sign.swisscom.ch/system`
- URL: `https://sign.swisscom.ch/system/api/process/{processId}/open/{personId}`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://sign.swisscom.ch/realms/swisscom-public/protocol/openid-connect/token` scopes: `sswp:process:read`
- TypeScript: <https://skmtc.dev/swisscom/apis/swisscom-sign-integration-api/docs/api/process/:processId/open/:personId/post.ts> (a function with typed inputs; its response is checked against the schema)

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 the process has not been released yet or the signer has not been invited yet, an error is returned. For unreleased processes, /process/{processId}/setup can be used.

Preconditions:
* The process must have been released via /process/{processId}/release.
* A signer must not have the status `WAITING`. This does not apply to the initiator.

## Path parameters

- `processId` string, uuid, required
- `personId` string, required: The system-assigned identifier or the external reference from your system can be used to identify the person. If several signers share the same external reference (e.g. after a replacement), the signer with status `WAITING` or `PENDING` is used.

## Request body

- ProcessOpenRequest: Request to open a signing process for a specific participant.
  - `language` string: Preferred UI language (BCP-47). Allowed: en-GB, de-CH, fr-CH, it-CH.
  - `lifecycle` 'PERMANENT' | 'TEMPORARY': Controls how parameters (e.g., language, URLs, authorization settings) are applied when opening the process: * `PERMANENT` – Configuration is saved to the process and reused. * `TEMPORARY` – Configuration only applies to this request.
  - `skipAuthorization` boolean: If `true`, the response URL includes a short-lived one-time code that is redeemed immediately when opening the URL (valid for ~15 minutes, single use). This bypasses the usual pre-step challenge but **still enforces full authorization** by the system. If `false` (default), the user must pass the standard authorization flow after opening the URL.
  - `backUrl` string: Back URL to the calling application. When set, the UI displays a Home button in the navigation that redirects the user to this URL.
  - `successUrl` string: Success URL invoked via GET after the signing succeeded. Query parameters (e.g., process and participant identifiers) are appended by the system. The endpoint should respond with an HTTP redirect suitable for browsers.
  - `authentication` ProcessAuthentication: INTERNAL ONLY: Authentication for the first-party namespace. Requests from other clients are ignored.
    - `identity` string, uuid, required: Caller-side user identifier (UUID).
    - `namespace` 'MSA' | 'MSAINT', required: Logical namespace of the first-party application (restricted).
  - `scope` string: Scope: defines the scopes that are requested on the token.
  - `mode` 'DEFAULT' | 'EMBEDDED': Mode: defines the display mode of the process page.

## Response `200`

You receive an URL specific to the subscriber with a defined validity period.

- ProcessOpenResponse: Response with the deep link to open the process in Swisscom Sign UI.
  - `id` string, uuid: Process identifier.
  - `url` string, uri: Participant-specific URL to open the process.

## Other responses

- `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:read`.
- `404`: Process or participant not found, or the process does not belong to the organization of the token.
- `409`: The process has not been released yet, the signer has not been invited yet (status `WAITING`), or a general error occurred.

---

[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)