Getting Started

If you look for a simple way to bring electronic signing capabilities to your system you’re in the right place.

The Swisscom Sign platform provides a REST API that allows your system to start, release and monitor signing processes.

This API doc will help you with the integration by explaining the necessary steps and the logic of the API so you can bring its value to the users of your system as quickly as possible.

If you want to jump directly to the API contract, go here.

Terms and Conditions

As an Integrator download and read the terms and conditions of our API.

The conditions are also available in German, French and Italian.

By proceeding with the integration, you confirm that you have read and understood the terms and conditions for the Swisscom Sign Integration API and that you are authorized to conclude this agreement on behalf of the customer.

Ways to integrate

There are different possibilities of an integration of this API.

You integrate it into your application and let your users provide the credentials to use it. That means users of your application will need to subscribe themselves if they choose to make use of Sign within your application.
You integrate it into your application with your own credentials and let your users use it without providing their own credentials. That means you subscribe and provide Sign to your users within your own offering.
If you require advanced features like a custom domain for the Sign UIs, your own certificates, encryption keys and SSO, then please contact us here.

Services

States

A signing process has a specific state at each point. This determines which services are accessible and which changes can be made to the signing process.

There are possible 4 states:

State	Description
CREATED	The signing process has been created and files can now be attached to it.
PENDING	The signing process has been released. Files can no longer be attached and you are waiting for signatures.
COMPLETED	All required signatures have been made and the signing process is finished.
EXPIRED	At least one signature is still missing

Transitions

The following graphic can be used to illustrate the relationship between the statuses and the available services in the respective status.

Create

Type	REST Service	Minimal status prerequisite	Description
POST	`/process`	-	You can start a new signing process via this REST service. To do this, you build the payload in the body according to your wishes and pass it in the request. The status of the process after this service is created.
POST	`process/{processId}/attach`	CREATED	If you created the signing process with the previous REST service, you must add at least one attachment in the form of a document. Currently only files of type `application/pdf` are allowed. If you want to attach multiple files you can call this service multiple times but have to wait for the completion of each file attachment request before you upload another one.
POST	`process/{processId}/setup`	CREATED	The previously created signing process can be configured manually by a user. For this purpose, we give you a URL in the response of this service to which you can forward the user. The process changes to the status PENDING, as soon as the user successfully completes the setup.
POST	`process/{processId}/release`	CREATED	If you want to start the signing process without manual input of a user you can do this via this service. Provided that the previously created document meets all requirements. The process changes to the status PENDING, if the service could be executed successfully. Additionally, the email notifications can be controlled. These can be configured down to the individual and depending on the mail type. The returned URLs can be used for the asynchronous mail process if the mails want to be sent by the third party system. URLs to open a process directly from the third party system can be obtained via the `/process/{id}/open/{personId}` service. Before this step, the positioning of the visual signature is usually forgotten. This must be done when creating the document.
POST	`process/{processId}/open/{personId}`	PENDING	The previously released signing process can be opened for a specific signer and signed directly. The service offers the possibility of feedback integration with return URLs. The URL returned here is time limited and should not be sent as a link in an email.

Read

Type	REST Service	Minimal status prerequisite	Description
GET	`process/{processId}`	CREATED	You can use this service to query the JSON model of one of your created documents.
GET	`process/{processId}/status`	CREATED	Here you can check the current status of one of your documents via this service.
GET	`process/{processId}/file/{fileId}`	CREATED / COMPLETED	You can get process related files through this service. It is possible to download the original file for each status of the process. However, you can get signed files only when the status of the process is completed.
GET	`process/{processId}/record`	CREATED	With this service you will receive all written auditing records in addition to the document. Swisscom Sign writes different records at different times. More information can be found in the OpenAPI documentation.

Process Authorization

Authorization for accessing a signing process follows a defined order, depending on the role (initiator or invitee).

For Initiators

Process ownership – the process directly belongs to the initiator.
Team membership – the process belongs to a team within an organization the initiator is a member of.
Verified email address – the initiator’s optionally verified account email address matches the one stored in the process.
Verified mobile number – the initiator’s optionally verified account mobile number matches the one stored in the process.
Fallback: code authorization – if none of the above conditions are met, a code-based authorization is provided:

5a. If a mobile number is stored in the process → an SMS code is sent.

5b. Otherwise → an email code is sent.

For Invitees

Verified email address – the invitee’s optionally verified account email address matches the one stored in the process.
Verified mobile number – the invitee’s optionally verified account mobile number matches the one stored in the process.
Fallback: code authorization – if none of the above conditions are met, a code-based authorization is provided:

3a. If a mobile number is stored in the process → an SMS code is sent.

3b. Otherwise → an email code is sent.

Open Request

Additionally, a one-time code can be requested via the Open Request:

The code is valid for 30 seconds and can be redeemed exactly once.
With this code, authorization to the process is automatically granted in the context of the respective person.
In this case, the system must guarantee that the user is authorized to access the process in the context of this person.
If the code is expired or invalid, the standard authorization order as described above is executed.

Authentication

All services are protected and require the presentation of a valid token for access. Tokens can be obtained via the OAuth2 client credential flow. The endpoint to obtain a token is specified in the API contract. You need to provide credentials (Client ID and Client Secret) to be eligible for a token.

There are two types of client credentials:

Public Tenant (self-managed)
- Credentials can be managed directly by the organization within its active subscription.
- Each organization can create and revoke its own credentials.
- These credentials are restricted to the specific organization they belong to.
Corporate Tenant (onboarding-based)
- Credentials are issued as part of the corporate onboarding process.
- They are tied to the dedicated corporate tenant of the customer.
- Management and distribution of credentials are handled in coordination with the provider.

Tokens issued with these credentials carry scopes (e.g. sswp:process:create, sswp:process:read) and may include claims (e.g. organization_id) that define and restrict access.

Testing

We have a second environment for testing purposes. To obtain credentials for it create an account on the TEST sign cockpit. It looks like the productive page but the url has “test” in front:

You will be asked to login or sign up for the test environment too. Provide a username and password combination and an email address you control (you will receive an activation mail). Once you are in the TEST cockpit you need to subscribe to a plan to obtain credentials. This is free if you provide a testing credit card found here. Once you have an active subscription, go to the API Credentials tab and create client id and secret for TEST.

Now, you can authenticate at the APIs of our TEST environment. Use our swagger UI as your REST client or any other tool of your choice with the openAPI file provided there. The endpoints for test are preconfigured as follows:

https://test.sign.swisscom.ch/system

https://test.sign.swisscom.ch/realms/swisscom-public/protocol/openid-connect/token

Note that if you want to test a full end-to-end process with signing you are restricted to AES and EES signature levels. This is because QES requires a mobile app which currently is not publicly available in the test version.

Support

If you have questions about the integration please visit our general help landing page. If the problem cannot be solved with this guide and the general sign help pages, our support team is available from Monday to Friday from 08:00 - 17:00 on 0800 829 444.

0800 829 444