LogoSignature Service

Web Client

The Web Client integration provides a flexible, user-friendly way to collect electronic signatures without embedding a full signing flow in your application. In this variant, you upload one or more documents to the platform and receive a unique signing URL. This URL can then be presented to the end user, for example, in an email, within a web portal, or inside a mobile app.

The signing experience is fully hosted by the Signature Service, ensuring compliance, accessibility, and security, while you remain in control of the user journey and the document lifecycle. After the signing process is complete, the Signature Service can either notify your application via a callback/webhook or allow your application to retrieve the status through API polling.

This approach provides an optimal balance between integration simplicity and control over the user experience.

API Endpoints

Requesting a signature

The document(s) to be signed are provided to the /signDoc API, together with the signing service profile and any additional metadata required by the requested service.

If the chosen signing service supports batch signing, which means signing multiple digests at once, multiple documents can be provided in the documents array.

signDoc API request body:

{
  "documents": [
    {
      "id": "documentId", <1>
      "data": "JVBERi0xLjMKJcTl8uXrp...", <2>
      "title": "Document title" <3>
    }
  ],
  "signingServiceProfile": "signing-profile-identifier", <4>
  "lang": "en", <5>
  "metadata": { <6>
    "firstname": "value", <7>
    "lastname": "value" <8>
  },
  "signatureClientConfiguration": { <9>
    "redirectUrl": "https://example.com/app?status={response}" <10>
  },
  "callbackUrl": "https://example.com/callback/identifier?queryparam=documentId", <11>
  "userID": "testUser" <12>
}
  1. ID of the document. Required for batch signing only.
  2. Base64-encoded PDF document to be signed.
  3. Document title. Not used in the context of this API; it can be any non-blank value.
  4. The signing service profile identifier. Must be enabled for the current organization.
  5. The preferred language of the SCS responses, specified according to RFC 5646.
  6. Collection of generic metadata required by the targeted signingServiceProfile. See the examples section for additional details.
  7. The first name(s) of the user to be used in the visual signature.
  8. The last name of the user to be used in the visual signature.
  9. Optional signature client configuration. This may be required depending on the signingServiceProfile. See the examples section for additional details.
  10. Optional URL where the user is redirected when canceling or completing the signature process.
  11. Optional callback URL where any update to the request status is sent. If not provided, the signPolling endpoint should be called.
  12. The identifier of the user signing the request.

Additional metadata:

  • headerTitle: Custom title displayed in the Web Client's navigation controller.
  • headerSubtitle: Custom subtitle displayed in the Web Client's navigation controller.

The API returns a JSON object as shown below.

The PENDING status indicates that the request is awaiting a signature from the end user. The authenticationUrl should be provided to the end user to initiate the signing process.

signDoc response body:

{
    "status": "PENDING", <1>
    "responseID": "WyJjZDdmNzQxYi1hZTVkLTQzNDEtOTBlMy1iYjQ4YzJk", <2>
    "authenticationUrl": "https://sign.swisssign.com/websign/...", <3>
    "document": "JVBERi0xLjMKJcTl8uXrp...",<4>
    "documents": { <5>
      "documentId": "JVBERi0xLjMKJcTl8uXrp...",
      "documentId2": "JVBERi0xLjMKJcTl8uXrp..."
    }
 }
  1. Status of the signature request. Can be PENDING, EXPIRED, SUCCESS, or ERROR in the case of document certification.
  2. Response identifier.
  3. Authentication URL to display to the end user when step-up authentication is required to sign.
  4. Base64-encoded signed document.
  5. Base64-encoded signed documents for batch signing.

Please refer to the examples section for detailed examples of signature requests for our different signing services.

Polling signature status

The status of the signature request can be retrieved using the /signPolling API with the following request body:

signPolling request body:

{
    "requestID": "responseID" <1>
}
  1. Value of the responseID attribute received in the response from the signDoc API.

The response body is identical to the signDoc API response body.

Once a status other than PENDING is returned to the Relying Party system, the request is permanently removed from our system, and its status can no longer be retrieved.

The /signPolling API cannot be used if a callbackUrl was set for the signature request.

Examples

Simple Electronic Signature

The example below demonstrates how to use the SCS APIs to initiate a Web Client signature request for a Simple Electronic Signature.

cURL example for a Simple Electronic Signature:

    curl --location \
      --request POST 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/signatures/signDoc' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password \
      --data-raw '{
        "documents": [
          {
            "data": "JVBERi0xLjMKJcTl8uXrp...",
            "title": "Document title"
          }
        ],
        "metadata": {
          "firstname": "John",
          "lastname": "Doe"
        },
        "signingServiceProfile": "swisssign-seal",
        "signatureClientConfiguration": {
          "redirectUrl": "http://example.com?data={response}"
        },
        "userID": "myUserId"
      }'

cURL example for a Simple Electronic Signature with batch signing:

    curl --location \
      --request POST 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/signatures/signDoc' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password \
      --data-raw '{
        "documents": [
          {
            "id": "doc1",
            "data": "JVBERi0xLjMKJcTl8uXrp...",
            "title": "Document title"
          },
          {
            "id": "doc2",
            "data": "JVBERi0xLjMKJcTl8uXrp...",
            "title": "Document title"
          }
        ],
        "metadata": {
          "firstname": "John",
          "lastname": "Doe"
        },
        "signingServiceProfile": "swisssign-seal",
        "signatureClientConfiguration": {
          "redirectUrl": "http://example.com?data={response}"
        },
        "userID": "myUserId"
      }'

Qualified Electronic Signature

The example below demonstrates how to use the SCS APIs to initiate a Web Client signature request for a Qualified Electronic Signature (QES).

cURL example for a Qualified Electronic Signature use case:

    curl --location \
      --request POST 'https://mtl.sandbox.pre.swissid.ch/rss/admin/admin/api/v3/organizations/\{organizationId}/signatures/signDoc' \
      --header 'Content-Type: application/json' \
      --user 'username:password' --cert-type P12 --cert client-cert.p12:password \
      --data-raw '{
        "documents": [
          {
            "data": "JVBERi0xLjMKJcTl8uXrp...",
            "title": "Document title"
          }
        ],
        "metadata": {
          "firstname": "John",
          "lastname": "Doe"
        },
        "lang": "de",
        "signingServiceProfile": "swisssign-qes-zertes",
        "signatureClientConfiguration": {
          "redirectUrl": "http://example.com?data={response}",
          "loginHint": "user_email@example.com"
        },
        "userID": "rss_sub"
      }'
  1. The userID must match the rss_sub attribute, which is the unique identifier of the SwissID user that can be retrieved through the SwissID Introspection Endpoint.
  2. The loginHint is mandatory and must match the email address of the SwissID account, which is provided in the email claim.
  3. The lang attribute selects the language of the authentication page for the user.

Web Client Behavior

The Web Client can behave in different ways when the user signs a document.

Identifying signable fields

The Web Client determines which signature fields a user can sign based on each field's name attribute (PDF standard attribute "T").

A user can sign a field if its name matches one of the following patterns:

  • the username pattern: smartcontract_sign_field_{username} or smartcontract_sign_field_{username}_{fieldIndex}
  • the sequence pattern: smartcontract_sign_field_{signatoryIndex} or smartcontract_sign_field_{signatoryIndex}_{fieldIndex}
  • the unassigned field pattern: smartcontract_sign_field_unassigned_{fieldIndex}

Where:

  • {signatoryIndex} is a numeric index identifying a signatory when a document is signed by multiple users.
  • {fieldIndex} is a numeric index used to define the order in which the fields should be presented to the user when a single user can sign multiple fields within the same document. This index is shared between the different patterns, and fields that do not match any pattern should appear at the end.

Fields that do not match any pattern will be available to any user.

Example 1: Order for the 1st signatory

  1. smartcontract_sign_field_1_1
  2. smartcontract_sign_field_1_2
  3. smartcontract_sign_field_unassigned_3
  4. smartcontract_sign_field_1_4
  5. smartcontract_sign_field_unassigned_6
  6. another1
  7. another2

Example 2: Order for the 2nd signatory

  1. smartcontract_sign_field_2_1
  2. smartcontract_sign_field_unassigned_3
  3. smartcontract_sign_field_2_4
  4. smartcontract_sign_field_2_5
  5. smartcontract_sign_field_unassigned_6
  6. another1
  7. another2

Username pattern

This pattern restricts access to the signature field by matching against the currently authenticated user's username.

The {fieldIndex} allows a single user to have multiple signature fields without causing PDF field name collisions.

Example:

If the username is 01234567-89ab-cdef-0123-456789abcdef, the user will be permitted to sign fields named:

  • smartcontract_sign_field_01234567-89ab-cdef-0123-456789abcdef
  • smartcontract_sign_field_01234567-89ab-cdef-0123-456789abcdef_1
  • smartcontract_sign_field_01234567-89ab-cdef-0123-456789abcdef_2
  • etc.

Sequence pattern

This pattern is used for documents requiring signatures from multiple users in a sequential chain.

The Web Client allows the current user to sign the field(s) that match the lowest {signatoryIndex}. Once the current user has signed, the field(s) associated with the next lowest index will be presented to the next signatory.

Example:

If the fields are smartcontract_sign_field_1_1, smartcontract_sign_field_1_2, smartcontract_sign_field_2_1, and smartcontract_sign_field_3_1:

  • the first user can only sign smartcontract_sign_field_1_1 and smartcontract_sign_field_1_2
  • the second user can only sign smartcontract_sign_field_2_1
  • the third user can only sign smartcontract_sign_field_3_1

Unassigned field pattern

Unassigned fields can be signed by any user. This pattern can also be used to control field order.

If a field does not specify a name attribute, which is allowed by the PDF standard, the Web Client automatically adds one using the following pattern: smartcontract_sign_field_unassigned_{fieldIndex}.

The generated {fieldIndex} continues the existing sequence.

Example:

In a multi-user scenario, if a document has one unassigned field and two fields without names, the resulting fields will be:

  • smartcontract_sign_field_unassigned_1 => (already present)
  • smartcontract_sign_field_unassigned_2 => (automatically added)
  • smartcontract_sign_field_unassigned_3 => (automatically added)

If the first user decides to sign only smartcontract_sign_field_unassigned_2, then the next user can sign smartcontract_sign_field_unassigned_1 and/or smartcontract_sign_field_unassigned_3.

Mixed patterns

The username and sequence patterns cannot both be used in the same document. In such a case, only fields matching the username pattern will be processed, along with unassigned fields, which are always processed.

In addition, fields that do not match any of the above patterns can be signed by any user.

Example:

With the following fields:

  • smartcontract_sign_field_01234567-89ab-cdef-0123-456789abcdef_1
  • smartcontract_sign_field_01234567-89ab-cdef-0123-456789abcdef_2
  • smartcontract_sign_field_1_1
  • smartcontract_sign_field_1_2
  • smartcontract_sign_field_unassigned_3
  • smartcontract_sign_field_unassigned_4
  • Signature1
  • Signature2

If the first user is 01234567-89ab-cdef-0123-456789abcdef, they can place their visual signature in:

  • smartcontract_sign_field_01234567-89ab-cdef-0123-456789abcdef_1
  • smartcontract_sign_field_01234567-89ab-cdef-0123-456789abcdef_2
  • smartcontract_sign_field_unassigned_3
  • smartcontract_sign_field_unassigned_4
  • Signature1
  • Signature2

Then, a second signatory will be able to sign:

  • smartcontract_sign_field_1_1
  • smartcontract_sign_field_1_2

and any remaining fields among:

  • smartcontract_sign_field_unassigned_3
  • smartcontract_sign_field_unassigned_4
  • Signature1
  • Signature2

In another scenario, with the same fields, if the first user is not 01234567-89ab-cdef-0123-456789abcdef, they can place their visual signature in:

  • smartcontract_sign_field_1_1
  • smartcontract_sign_field_1_2
  • smartcontract_sign_field_unassigned_3
  • smartcontract_sign_field_unassigned_4
  • Signature1
  • Signature2

Then, a second user who is also not 01234567-89ab-cdef-0123-456789abcdef will only be able to choose from the remaining fields:

  • smartcontract_sign_field_unassigned_3
  • smartcontract_sign_field_unassigned_4
  • Signature1
  • Signature2

Finally, if the user 01234567-89ab-cdef-0123-456789abcdef has to sign, they will have both of their dedicated fields:

  • smartcontract_sign_field_01234567-89ab-cdef-0123-456789abcdef_1
  • smartcontract_sign_field_01234567-89ab-cdef-0123-456789abcdef_2

plus any remaining fields among:

  • smartcontract_sign_field_unassigned_3
  • smartcontract_sign_field_unassigned_4
  • Signature1
  • Signature2

Signature field interaction

Once the Web Client has identified which signature fields the current user is authorized to sign, the user's interaction with the document will vary depending on the number of available fields.

No signature field

When the document does not include any signature field that the user is authorized to sign, they may freely place their signature anywhere on the document and adjust its position and size as needed.

Single signature field

When the document has exactly one signature field, the signature field will be automatically selected for the user.

Multiple signature fields

When the document contains two or more signature fields, automatic selection is disabled. The user must manually navigate through the document and click the specific field(s) they wish to sign.

Required and optional fields

When a document contains multiple signature fields, they can be marked as either required or optional using the PDF standard attribute "Ff" with value "2":

  • Required fields: a signature field is considered required if its required flag is set in the PDF. The user must sign all required fields to complete the signing process. Note: If a required field uses the unassigned field pattern, it is not mandatory for the current user to sign it.
  • Optional fields: a signature field is considered optional if its required flag is not set. The user can choose to sign or ignore these fields.

If all available fields are optional, the user must sign at least one of them to successfully sign the document.

Example:

If the fields are smartcontract_sign_field_1 (required), smartcontract_sign_field_2 (required), smartcontract_sign_field_3 (optional), and smartcontract_sign_field_unassigned_1 (required):

  • signing the first two fields is mandatory: smartcontract_sign_field_1 and smartcontract_sign_field_2
  • signing the other two fields is optional, even though smartcontract_sign_field_unassigned_1 is marked as required because it uses the unassigned field pattern

Summary

The following table summarizes how the Web Client displays fields based on the naming pattern and the required flag:

Naming patternOptionalRequired
Assigned to meOptionalMandatory
Assigned to someone elseHiddenHidden
UnassignedOptionalOptional
No matchOptionalOptional

Sign all button

When a document contains multiple signature fields, the Web Client may display a Sign all button.

This feature allows the user to apply their signature to multiple fields at once, without needing to navigate to and sign each field individually.

Note 1: The Sign all button signs only the mandatory fields. Any optional fields will remain unsigned.

Note 2: The Sign all button is not available if it has been disabled in the configuration (allowSignAllCapability, true by default).

Envelopes

For envelopes, which are batches of multiple documents, a similar Sign all button may be available in the document list view.

This allows the user to quickly sign all mandatory fields in all documents in the envelope at once.

Visual signature output

When the user completes the signing process, the resulting PDF will display visual signatures at the locations of the signed signature fields.

However, the underlying annotation type used to represent these visual elements depends on how many fields were signed:

  • when the user signs only one field, the Web Client applies a single visual signature annotation to the document, which is also used to embed the digital signature.
  • when the user signs multiple fields, whether one by one or using the Sign all button, the Web Client creates one invisible digital signature and adds all visual signatures using rubber stamp annotations.

Release Notes

Previous Page

Hash Signing API

Next Page

On this page

API EndpointsRequesting a signaturePolling signature statusExamplesSimple Electronic SignatureQualified Electronic SignatureWeb Client BehaviorIdentifying signable fieldsUsername patternSequence patternUnassigned field patternMixed patternsSignature field interactionNo signature fieldSingle signature fieldMultiple signature fieldsRequired and optional fieldsSummarySign all buttonEnvelopesVisual signature output