Getting Started

Introduction to REST-APIs

Let's Sign provides a REST API that enables integration with digital processes that require digital signatures. All operations available from the user interface can be performed using the APIs.

Let's Sign exposes two types of APIs; the Signature Creation Service APIs (SCS), which provide an interface to a remote signing service, and the Signing Room-based APIs, which provide an interface to our full web-based signing solution.

This guide is intended to help developers get started with basic REST API integration. Full documentation of the service is available as an OpenAPI definition.

Signature Creation Service APIs

The Signature Creation Service (SCS) provides a simple and generic interface for remote hash signing operations supporting a wide range of signature types from different providers.

This API is designed for Relying Party services that want to integrate digital signatures without having to send sensitive documents to the cloud (hash signing).

To do this, the Relying Party must implement by its own the Signature Creation Application (SCA), which prepares the document to be signed and, in the case of an electronic signature, guides the user through the digital signature workflow.

To reduce the complexity of this process, SwissSign offers Let's Sign, a Signature Creation Application that can be installed on premise and supports many different use cases (electronic seal, electronic signature, collective signature, etc.).

The API also provides the ability to receive PDF documents for signing, and handles the preparation and integration of the digital signature into the document. In this context, the Signature Creation Application to be used can be one of the built-in software (mobile / web) provided by SwissSign AG.

Read out SCS APIs examples for more information about the APIs.

Signing room-based APIs

The purpose of the Signing room-based APIs is to provide a complete signing process, from the onboarding of signatories to the digital signing of PDF documents using our web or mobile signing applications.

A signing room is a dedicated space assigned to an organisation where signatories can be invited to sign documents. A signing room can accommodate as many signatories as required and a signatory will never have access to any information other than the signing request that belongs to them. Depending on the use case, it's possible to create one signing room per signatory or one signing room for all signatories.

An administrator of the organisation can give manager rights to one of the signatories to access the signing room from the user interface and manage the whole signing room (invite new signatories, manage signing requests, download signed documents, etc.).

Read out Signing room-based APIs examples for more information about the APIs.

OpenAPI

The Let's Sign REST APIs has an OpenAPI description that follows the OpenAPI Specification 3.0.1. The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs that allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or by inspecting network traffic.

Documentation is provided as a single openapi.json definition file per API version.

The OpenAPI definition can then be used by documentation generation tools to view the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

In addition, the sandbox environment exposes a Swagger UI to visualise and interact with the REST APIs.

Please refer to the environments section to get access to the OpenAPI definition.

Environments

Let's Sign Sandbox

SwissSign provides a complete test and demo environment that can be used by any partner and customer willing to start integration without an On-Premise environment ready or up-to-date.

The Sandbox environment provides the full Let's Sign ecosystem, including test certificates for all supported built-in signing services.

Please contact us to request an account on this environment.

On-Premise installation

A test environment can be provided and easily installed in your own infrastructure.

Please contact us to request the installation package and the required licenses.

Signing Services Profiles

Getting started

Step 1: Request a test account

TODO The test account can be verified by simply listing available organizations using the provided credentials.

Step 2: Setting up your organization

An organisation must be set up before it can be used with the Signing Room-based APIs. The organisation can be configured either through the GUI or through the APIs (except for security settings related to invitations, which can only be configured through the GUI).

This step is not required if you plan to use only the SCS APIs.

Create new workflows

From the Settings > Workflows view it is possible to manage and create new workflows for the organisation.

A workflow consists of a business use case associated with a specific signature type and provider. It is described by a name and a description that helps the user to identify the correct workflow for the document to be signed.

Once a workflow has been created, it can be enabled for a signing room and used by managers and/or the REST APIs.

Configuration invitation settings

From the Settings > Invitations view, it is possible to configure some security settings related to the signing room invitations.

Enable domain name restrictions

Defines the domain name that can be invited into the organisation.

By default, all email addresses are allowed. It's possible to whitelist domain names that can be invited (global restrictions) or only domain names that can get privileged permissions (manager) to the signing rooms.

Single invitation per organization

When enabled, new users to the organisation must to accept a single invitation to join the organisation. Once accepted, the users can be added to any signing room in the organisation without having to go through the invitation process.

User lookup

When enabled, users can to take advantage of the auto-completion feature when submitting signing requests or inviting new users to their signing room from the GUI.

Users will be able to search for any existing user in the organisation. It's possible to restrict the feature to only a set of specific domain names (e.g internal employees).

Create new signing rooms

From the Signing rooms view, it is possible to manage and create new signing rooms.

When creating a new signing room, a name and the list of workflows to be activated must be defined.

Step 3: Walk through the examples

Once you have been granted access to the Let's Sign environments, you can explore the APIs using the example provided in the following section.

Examples

This section provides examples of the APIs using the cURL command-line tool.

The full list of operations, including documentation on request body, response body and error codes is documented in the OpenAPI reference.

For the sake of clarity, this guide does not include examples of response bodies. Please refer to the OpenAPI definition for the response format.

Getting information about available organizations

The following example lists all organizations that can be administrated using the provided credentials.

getOrganizations example

curl --location \
--request GET 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations' \
--header 'Content-Type: application/json' \
--user 'username:password' <1>

Credentials of the API account

The response body consists to a paged collection.

getOrganizations response body

{
  "content": [
    {
      "dataRetentionInDays": 30, <1>
      "enabledSmartContractIdentifiers": [ <2>
        "scs-qes-zertes",
        "scs-qes-eidas",
        "scs-ses-swisssign"
      ],
      "name": "Company Name", <3>
      "id": "173419d6-fb74-4752-95bf-b7eaf8639ce2" <4>
    }
  ]
}

Number of days signing requests are stored into the system before being permanently deleted
Signing services profiles activated for the organization
Display name of the organization
Unique identifier of the organization

The id attribute will need to replace the {organizationId} placeholder in all subsequent APIs.

Signature Creation Service APIs

The purpose of the Signature Creation Service (SCS) APIs is to offer remote hash signing operations with any of the supported signing services.

Depending the signing service profile selected, the API is either synchronous (e.g an electronic seal) or asynchronous if a user action is required to unlock the signature.

Request signature

This API allows you to sign either digest(s) or PDF document(s) with a specific signing service profile.

The request body sent to the /signDoc API is documented below.

signDoc API request body

{
  "documentDigests": { <1>
    "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1", <2>
    "hashes" : [ <3>
        "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg="
    ],
    "ids" : [ <4>
    ],
    "titles": [ <5>
    ]
  },
  "documents": [ <6>
    {
    "title": "Document title", <7>
    "data" : "JVBERi0xLjIgCjkgMCB...", <8>
    "id" : null <9>
    }
  ],
  "signingServiceProfile": "signing-profile-identifier", <10>
  "lang": "en", <11>
  "metadata": { <12>
    "key": "value"
  },
  "userID": "testUser", <13>
  "expiresAt" : "300", <14>
  "callbackUrl" : "https://example.com/callback/" <15>
}

Document digest(s) to be signed. Cannot be set in conjunction with the `documents' attribute.
Hashing algorithm OID used to compute the document hash(es). Currently only SHA-256 is supported.
Base64-encoded document(s) hash(es), to be signed. If more than one digest is provided, the signing service must support batch signing.
Optional ids, only required if multiple document digests are available.
Optional titles, required only for specific signing service profiles.
Document file(s) to be signed. Cannot be set in conjunction with the `documentDigests' attribute.
Title of the document being signed.
Base64-encoded raw data of the PDF file to be signed
Optional ID, only required if there are multiple documents
The signing service profile identifier. Must be enabled for the current organisation.
The preferred language of the SCS responses, specified according to RFC5646
Collection of generic metadata required by the targeted signingServiceProfile
The identifier of to the user signing the request
The number of seconds before the request automatically expires and gets deleted from the system. Minimum 30 seconds.
The endpoint URL to send the status callback to. Optional (document signing only).

The API returns a JSON object represented as below.

signDoc response body


{
    "status": "PENDING", <1>
    "responseID": "WyJjZDdmNzQxYi1hZTVkLTQzNDEtOTBlMy1iYjQ4YzJk", <2>
    "authenticationUrl": "data:text/html;base64,PCFET0NUWVB...", <3>
    "signature": null, <4>
    "signatures": null, <5>
    "error": null, <6>
    "errorMessage": null <7>
 }

Status of the signature request. Can be PENDING, SUCCESS, CANCEL, TIMEOUT, ERROR
Response identifier to be used as 'requestID' when requesting signature status, when status is 'PENDING'. Not provided in other statuses.
Authentication URL to display to end-user, when step-up authentication is required to sign
Signature value, when a single signature has been requested
Signature values, when multiple signatures have been requested
Error code, in case the 'status' component is set to 'ERROR'
End-user error message, in case the 'status' component is set to 'ERROR'

The signature request is discarded server-side after the `SUCCESS' status is retrieved or sent in a callback.

Get signature status

In the case of asynchronous processing, the status of the signature request can be retrieved using the /signPolling API with the following request body :

signPolling request body

{
    "requestID": "responseID" <1>
}

Value of the responseID attribute received in response of the signDoc API

The response body is the same as signDoc API.

Alternatively, for signature requests involving PDF documents, it is possible to specify a callback URL that will be called if the status of the signature request changes. The same object as the /signPolling response body will be posted to the specified URL. For security enhancements, the callback URL can include private identifier(s) and request parameters (e.g. API keys).

See the examples below for real cases of available signing services.

TODO

Cancel processing

In the case of asynchronous processing, a pending request can be cancelled using the /cancelProcessing API with the following request body :

cancelProcessing request body

{
    "requestID": "responseID" <1>
}

Value of the responseID attribute received in response of the signDoc API

Signing room-based APIs

The purpose of the Signing room-based APIs is to provide a complete signing process, starting from the on-boarding of the signatories to the digital signature of PDF documents using our web or mobile signing apps.

Although it is possible to set up the organization using the APIs (creating workflows, creating signing room), we recommend to configure it according to our quick start guide.

The examples below demonstrate the main operations offered by the APIs. For a complete list of all available operations, see 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' \ <1>
--header 'Content-Type: application/json' \
--user 'username:password' <2>

Identifier of the organization
Credentials of the API account

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' \ <1>
--header 'Content-Type: application/json' \
--user 'username:password' <2>

Identifier of the organization
Credentials of the API account

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

Your organisation may have one or more signing rooms, depending on your use case and how you want to integrate the APIs.

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' \ <1>
--header 'Content-Type: application/json' \
--user 'username:password' \ <2>
--data-raw '{
  "name": "My signing room", <3>
  "workflowIds": [
    "{workflowId}" <4>
  ]
}'

Identifier of the organisation
Credentials of the API account
Name of the signing room
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 for a single signatory

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' \ <2>
--data-raw '{
  "signatoriesEmails": [
      "user@example.com" <3>
    ],
  "documents": [
    {
      "payload": "JVBERi0xLjMK...", <4>
      "title": "Contract 2023 - 3423243" <5>
    }
  ],
  "message": "Please review and sign document", <6>
  "workflowId": "{workflowId}", <7>
  "callbackUrl" : null <8>
}'

Identifiers of the organisation and the signing room
Credentials of the API account
Email of the signatory. Alternatively, it is possible to use the signatoriesIds attribute with unique identifier of the signatory
Base64-encoded PDF file
Title or name of the document
Optional message that will be sent by email to the signatory
Workflow identifier for the signing request
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

Once the signing request has been submitted, the user is notified by email of the request.

Create signing request for multiple signatories

It's possible to request multiple signatories to sign a signature request by providing a list of users in sequential order. Users receive an invitation to sign the document after the previous user has successfully signed the document.

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' \ <1>
--header 'Content-Type: application/json' \
--user 'username:password' \ <2>
--data-raw '{
  "signatoriesEmails": [
      "user@example.com", "user2@example.com" <3>
    ],
  "documents": [
    {
      "payload": "JVBERi0xLjMK...", <4>
      "title": "Contract 2023 - 3423243" <5>
    }
  ],
  "workflowId": "{workflowId}", <6>
  "callbackUrl" : null <7>
}'

Identifiers of the organisation and the signing room
Credentials of the API account
Emails of the signatories
Base64-encoded PDF file
Title or name of the document
Workflow identifier for the signing request (optional if signing room contain a single workflow)
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

Create signing request to electronically seal a document

The Electronic Seal feature requires a workflow specifically designated as 'Electronic Seal'. It allows you to request an electronic seal for a PDF without any user interaction.

This API does not require a signatory to be part of the signing request. Once the response is received, the signed document can be downloaded immediately.

Create signing request for an electronic seal

curl --location \
--request POST 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/{organizationId}/rooms/{signingRoomId}/requests' \ <1>
--header 'Content-Type: application/json' \
--user 'username:password' \ <2>
--data-raw '{
  "documents": [
    {
      "payload": "JVBERi0xLjMK...", <3>
      "title": "N/A" <4>
    }
  ],
  "workflowId": "{workflowId}", <5>
}'

Identifiers of the organisation and the signing room
Credentials of the API account
Base64-encoded PDF file
Title or name of the document. This title is only used to distinguish the document in the web interface.
Workflow identifier for the electronic seal

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}' \ <1>
--header 'Content-Type: application/json' \
--user 'username:password' <2>

Identifiers of the organization, the signing room and the signing request
Credentials of the API account

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 or CERTIFIED.

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' \ <1>
--user 'username:password' \ <2>
--output signed.pdf <3>

Identifiers of the organization, the signing room and the signing request
Credentials of the API account
Destination file were to stored the binary file

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' \ <1>
--header 'Content-Type: application/json' \
--user 'username:password' <2>

Identifiers of the organization and the signing room
Credentials of the API account

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 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' \ <2>
--data-raw '{
  "email": "john.doe@example.com", <3>
  "locale": "de", <4>
  "manager": false, <5>
  "skipNotification": true, <6>
  "callbackUrl": null <7>
}'

Identifiers of the organisation and the signing room
Credentials of the API account
Email of the user
The correspondence language of the email, specified according to RFC5646
Whether the user should get manager permissions to the signing room
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
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

Getting Started

On this page