Document Certification API

The Document Certification API allows you to have documents sealed or certified with the organization’s trusted certificate. Unlike other variants, this process does not involve human signatories, it applies a digital seal that confirms document authenticity and organizational origin.

This is ideal for automated or system-driven use cases such as generating invoices, certificates, statements, or any official documents that must carry an electronic seal of trust.

The following DocMDP (Document Modification Detection and Prevention) permissions can be configured to control post-signing changes.

• No changes allowed (read-only)
• Form fill-in and digital signatures
• Annotations (commenting), form fill-in, and digital signatures

APIs Endpoints

The document(s) to be signed are provided in the /signDoc API with the signing service profile.

{
    "documents": [
    {
        "id" : "documentId", <1>
        "data": "JVBERi0xLjMKJcTl8uXrp...", <2>
        "title": "Document title" <3>
    }
    ],
    "signingServiceProfile": "signing-profile-identifier", <4>
    "metadata": { <4>
        "key": "value"
    }
}

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, can be a random non-blank value.
4. The signing service profile identifier. Must be enabled for the current organisation.
5. Collection of generic metadata required by the targeted signingServiceProfile.

The certified document is available in the document attribute of the response body.

{
    "status": "SUCCESS", <1>
    "responseID": "WyJjZDdmNzQxYi1hZTVkLTQzNDEtOTBlMy1iYjQ4YzJk", <2>
    "document": "JVBERi0xLjMKJcTl8uXrp...", <3>
    "documents": { <4>
        "documentId": "JVBERi0xLjMKJcTl8uXrp...",
        "documentId2": "JVBERi0xLjMKJcTl8uXrp..."
    }
}

1. Status of the signature request. Can be SUCCESS or ERROR in case of document certification.
2. Response identifier.
3. Base64-encoded signed document.
4. Base64-encoded signed documents (batch signing).

Examples

Electronic Seal

The example below demonstrates how to use the SCS APIs with an electronic seal, for document certification purpose.

cURL example for electronic seal signing service

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": "N/A"
        }],
        "signingServiceProfile": "demo-seal-certification",
        "metadata": {
            "pdfDocMDP": "1"
        }
    }'

1. The signingServiceProfile has to be changed in production environment with the identifier of your own electronic seal.
2. The pdfDocMDP metadata designates the protection to be applied to the certified document. Allowed values:
   • 1: No changes allowed (default value)
   • 2: Only form fill-in, signing and page adding actions are allowed
   • 3: Only commenting, form fill-in, signing and page adding actions are allowed
   • -1: no permission set, the document is signed with a regular invisible electronic signature

Electronic Seal (batch signing)

cURL example for electronic seal signing service

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": "N/A"
        },
        {
            "id": "doc2",
            "data": "JVBERi0xLjMKJcTl8uXrp...",
            "title": "N/A"
        }],
        "signingServiceProfile": "demo-seal-certification",
        "metadata": {
            "pdfDocMDP": "1"
        }
    }'

1. The signingServiceProfile has to be changed in production environment with the identifier of your own electronic seal.
2. The pdfDocMDP metadata designates the protection to be applied to the certified document. Allowed values:
   • 1: No changes allowed (default value)
   • 2: Only form fill-in, signing and page adding actions are allowed
   • 3: Only commenting, form fill-in, signing and page adding actions are allowed
   • -1: no permission set, the document is signed with a regular invisible electronic signature