LogoSignature Service

Signing Rooms API

The Signing Room API offers the most streamlined integration path.

In this model, you submit the documents to be signed along with the list of signatories, and the Signature Service manages the entire signing process from start to finish.

This includes creating and sending invitations, sending automatic reminders, handling the signing workflow, and delivering the finalized, signed document.

The service is 100% hosted in Switzerland, ensuring that all documents and associated metadata remain within Swiss jurisdiction throughout their lifecycle. All data is securely stored, protected according to Swiss data protection standards, and permanently removed after the defined data retention period.

This variant is ideal for organizations that want to integrate e-signature capabilities quickly and securely, without managing the user interactions or signature lifecycle manually.

Use cases

The section belows list the common operations automated with Signing Room APIs. For a complete list of operations, please refer to the OpenAPI definition.

Retrieve list of available workflows

The following example shows how to retrieve the list of workflows available for an organisation.

getWorkflows example

    curl --location \
      --request GET 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/settings/workflows' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password

The response body consists of a paged collection of workflows. The id attribute can be reused in subsequent APIs (create new signing room, create new signing request).

To retrieve all information about a specific workflow, the GET admin/api/v3/organizations/\{organizationId}/settings/workflows/\{workflowId} API can be used.

Retrieve list of available signing rooms

The following example shows how to retrieve the list of all signing rooms for an organisation.

getSigningRooms example

    curl --location \
      --request GET 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/rooms' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password

The response body consists of a paged collection of signing rooms. The id attribute can be reused in subsequent APIs.

To retrieve all information about a specific signing room, the GET API admin/api/v3/organizations/\{organizationId}/rooms/\{roomId} can be used.

Create a new signing room

The following example shows how to create a signing room.

createSigningRoom

    curl --location \
      --request POST 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/rooms' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password \
      --data-raw '{
        "name": "My signing room",
        "workflowIds": [
          "\{workflowId}"
        ]
      }'
  1. Identifier of the organisation
  2. Credentials of the API account
  3. Name of the signing room
  4. List of the workflows activated to the signing room

To manage existing signing rooms (update, delete), see the API references.

Create new signing request

Supported documents

The solution supports the signing of PDF documents. Embedding the signature does not change the format of the PDF document. There are no checks or conversions for specific target formats. In other words, a document submitted for signing in, for example, PDF version 1.7 will result in a signed PDF version 1.7 document. The solution also supports long-term signature validation.

Before signing the document, users have the option of filling in the form fields in the PDF document. If a signature field is defined in the PDF, the signer's signature is placed in that field. Otherwise, the signatory manually places the visual signature mark in the document.

Note: When a document is submitted, the system may reject it if it meets one of the following exceptions

  • Corrupted PDFs (includes all non-PDF files)
  • Encrypted PDFs
  • PDF protected against form-filling or signature (certified documents or with special docmdp permissions)

Create signing request

The following example shows how to create a new signing request for a single signatory.

Create signing request for a single user

    curl --location \
      --request POST 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/{organizationId}/rooms/{roomId}/requests' \ <1>
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password \ <2>
      --data-raw '{
        "signatoriesEmails": [ <3>
          "user@example.com"
        ],
        "documents": [
          {
            "payload": "JVBERi0xLjMK...", <4>
            "title": "Contract 2023 - 3423243" <5>
          }
        ],
        "message": "Please review and sign document", <6>
        "workflowId": "{workflowId}", <7>
        "callbackUrl": null, <8>
        "signatureOptions": {
          "sendAsEnvelope": false <9>
        }
      }'
  1. Identifiers of the organisation and the signing room
  2. Credentials of the API account
  3. Email of the signatory. Alternatively, it is possible to use the signatoriesIds attribute with unique identifier of the signatory
  4. Base64-encoded PDF file
  5. Title or name of the document
  6. Optional message that will be sent by email to the signatory
  7. Workflow identifier for the signing request
  8. A callback URL that will be notified when the status of the signing request change into the system (accepted or rejected by the user, expired, etc.). Definition of the callback is documented into the OpenAPI definition
  9. When multiple documents are set, defines whether the documents should be grouped as an envelope or individual signing requests. If false one signing request per document will be created and returned to the API.

Create signing request for multiple signatories

It's possible to request multiple signatories to sign a signature request by providing a list of users. The signing order can be either SEQUENTIAL only one signatory gets the document at a time, or PARALLEL where all signatories receives the signing invitation at the same time.

If a user refuses the signing request, the process is interrupted and the next users aren't notified of the signing request.

There is no limit to the number of signatories.

Create signing request for a collective signature

    curl --location \
      --request POST 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/rooms/\{signingRoomId}/requests' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password \
      --data-raw '{
        "signatoriesEmails": [
          "user@example.com", "user2@example.com"
        ],
        "documents": [
          {
            "payload": "JVBERi0xLjMK...",
            "title": "Contract 2023 - 3423243"
          }
        ],
        "workflowId": "\{workflowId}",
        "callbackUrl": null,
        "signingOrder": "SEQUENTIAL" <1>
      }'
  1. Define the signing order : SEQUENTIAL (default value) or PARALLEL

Disable notifications for a signing request

It is possible to disable email notifications sent by Signature Service for a signing request. The system integrating the APIs is then responsible for notifying the end-user of the new signing request, and status update of the signing request (expiration, completed, etc.).

Create signing request for a single user

    curl --location \
      --request POST 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/rooms/\{roomId}/requests' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password \
      --data-raw '{
        "signatoriesEmails": [
          "user@example.com"
        ],
        "documents": [
          {
            "payload": "JVBERi0xLjMK...",
            "title": "Contract 2023 - 3423243"
          }
        ],
        "message": "Please review and sign document",
        "workflowId": "\{workflowId}",
        "signatureOptions": {
          "skipNotifications": true <1>
        }
      }'
  1. Disable all notifications for the given request

When notifications are disabled, the system shall provide the signing invitation link to the signatory through a dedicated channel.

Get signing invitation URL of a signing request

Each signatory of a signing request gets a unique signing invitation link. This link can be retrieved using REST APIs to provide it to the user from different channels.

The same link is unique per request and signatory and can't be shared between users.

getSigningSigningInvitation example

    curl --location \
      --request GET 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/rooms/\{roomId}/requests/\{requestId}/invitations/\{signatoryId}' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password

Get status of a signing request

It's possible to retrieve the status of a signing request at any time using the request identifier available in the response body of the creation request.

If no callback URL has been set for a signing request, this API can be used to query its status at a reasonable interval (min. 2 seconds).

getSigningRequest example

    curl --location \
      --request GET 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/rooms/\{roomId}/requests/\{requestId}' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password

The status can have the following values:

  • ACCEPTED: Signing request has been accepted by all signatories
  • REFUSED: Signing request has been refused by one signatory
  • EXPIRED: Signing request has has expired
  • CANCELED: Signing request has been canceled by a user or the system (unexpected error)
  • CERTIFIED: Signing request is completed (PDF sealing workflow)

When status is ACCEPTED or CERTIFIED, the signed document(s) can be downloaded using dedicated API.

Downloading signed file(s)

This example demonstrates how to download a signed file for completed requests with status ACCEPTED.

The API returns the signed PDF file in binary format. For envelope requests with multiple files, the API returns an archive containing the signed files.

downloadSignedDocument example

    curl --location \
      --request GET 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/rooms/\{roomId}/requests/\{requestId}/payload' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password \
      --output signed.pdf

Alternative APIs are available to download a single document of a request, or the revision of a single signature in the case of a collective signature request. See the OpenAPI definition for more information.

Retrieve list of existing signatories

The following example shows how to retrieve the list of all signatories for a signing room.

getSignatories example

    curl --location \
      --request GET 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/rooms/\{roomId}/signatories' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password

The response body consists of a paged collection of signatories. The id attribute can be reused in the API to create a signing request.

To retrieve all information about a specific signatory, the GET API admin/api/v3/organizations/\{organizationId}/rooms/\{roomId}/signatories/\{signatoryId} can be used.

Invite new user into a signing room

User are automatically added into a signing room when they're requested to sign a new signing request. However, depending on the use cases, it's possible to invite explicitly the user to a signing room.

This API can be used, for example, to grant manager permissions to users so that they can access the user interface and manage documents in the signing room.

The following example shows how to invite a new user.

Invite user into the signing room

    curl --location \
      --request POST 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/rooms/\{roomId}/invitations' \ <1>
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password \ <2>
      --data-raw '{
        "email": "john.doe@example.com", <3>
        "locale": "de", <4>
        "manager": false, <5>
        "skipNotification": true, <6>
        "callbackUrl": null <7>
      }'
  1. Identifiers of the organisation and the signing room
  2. Credentials of the API account
  3. Email of the user
  4. The correspondence language of the email, specified according to RFC5646
  5. Whether the user should get manager permissions to the signing room
  6. Whether the user should receive an explicit invitation to join the signing room. It is recommended to skip the notification so that user gets only one invitation first time she/he receives the document
  7. A callback URL that will be notified when user has accepted the invitation to the signing room. Definition of the callback is documented into the OpenAPI definition

Document Certification API

Previous Page

Create invitation POST

Next Page

On this page

Use casesRetrieve list of available workflowsRetrieve list of available signing roomsCreate a new signing roomCreate new signing requestSupported documentsCreate signing requestCreate signing request for multiple signatoriesDisable notifications for a signing requestGet signing invitation URL of a signing requestGet status of a signing requestDownloading signed file(s)Retrieve list of existing signatoriesInvite new user into a signing room