Skip to main content

Signature API

Base path: /v1

Authentication and transport:

Endpoint Summary​

OperationMethod and pathPurpose
Verify signaturesPOST /signature/verifyValidate one or more signatures against provided hashes

Example: Verify Signatures (JSON)​

curl -X POST "https://api.swisscom.com/products/document-validator/document/v1/signature/verify" \
	-H "Authorization: Bearer <access-token>" \
	-H "Content-Type: application/json" \
	-d '[
		{
	  	  "hash": "DOCUMENT_HASH",
		  "signature": "BASE64_SIGNATURE"
	  	}
	]'
  • DOCUMENT_HASH is the hex-encoded hash of the signed document content.
  • BASE64_SIGNATURE is the Base64-encoded signature for that hash.
  • The endpoint also supports multipart/form-data with a signaturesToVerify field.

Response Format​

The response is a JSON object with a verifyresult array — one entry per submitted hash/signature pair. Each entry contains the document hash and a sigcheck object with the verification outcome.

The signature level (signaturelevel) in each entry of signerslist determines how to interpret the result:

Qualified Electronic Signature (QES)​

allsigsqual: true — all signers used a qualified certificate on a QSCD device.

{
  "verifyresult": [
    {
      "hash": "HEX_DOCUMENT_HASH",
      "sigcheck": {
        "numberofsigs": 1,
        "numberofsimplesigs": 0,
        "allsigsvalid": true,
        "allsigsqual": true,
        "allsigsusequalcert": true,
        "sigcheckresult": true,
        "allsigsltvenabled": false,
        "allsigsseal": false,
        "allsigcertsineidastrustedlist": false,
        "signerslist": [
          {
            "legalframework": "ZERTES",
            "signaturelevel": "QES",
            "signatureusage": "SIGNATURE",
            "signatureclassification": "QES_ZERTES_SIGNATURE",
            "isqualifiedsig": true,
            "isqualifiedzertessig": true,
            "isqualifiedcert": true,
            "privkeyinqualifiedsignaturecreationdevice": true,
            "signer": "SIGNER_FULL_NAME",
            "signingtime": null,
            "signingtimebasedontimestamp": true,
            "signaturecontainstimestamp": true,
            "dochashmatchessig": true,
            "sigexists": true,
            "issignature": true,
            "isseal": false,
            "sigcertstatus": 0,
            "sigcertcheckerrormsg": null,
            "sigcertcheckmsg": "CERTIFICATE_VALIDATION_LOG",
            "issuer": "ISSUER_DN",
            "issuerorg": null,
            "ltaentryexists": true,
            "ltaorgid": 1,
            "localizedsigcerterrorcheckmsg": null
          }
        ]
      }
    }
  ]
}

Advanced Electronic Signature (AES)​

allsigsqual: false, allsigsusequalcert: false — signer used a non-qualified certificate. Signer identity is a phone number.

{
  "verifyresult": [
    {
      "hash": "HEX_DOCUMENT_HASH",
      "sigcheck": {
        "numberofsigs": 1,
        "numberofsimplesigs": 0,
        "allsigsvalid": true,
        "allsigsqual": false,
        "allsigsusequalcert": false,
        "sigcheckresult": true,
        "allsigsltvenabled": false,
        "allsigsseal": false,
        "allsigcertsineidastrustedlist": false,
        "signerslist": [
          {
            "legalframework": "ZERTES",
            "signaturelevel": "AES",
            "signatureusage": "SIGNATURE",
            "signatureclassification": "AES_ZERTES_SIGNATURE",
            "isqualifiedsig": false,
            "isqualifiedzertessig": false,
            "isqualifiedcert": false,
            "privkeyinqualifiedsignaturecreationdevice": false,
            "signer": "SIGNER_PHONE_NUMBER",
            "signingtime": null,
            "signingtimebasedontimestamp": true,
            "signaturecontainstimestamp": true,
            "dochashmatchessig": true,
            "sigexists": true,
            "issignature": true,
            "isseal": false,
            "sigcertstatus": 0,
            "sigcertcheckerrormsg": null,
            "sigcertcheckmsg": "CERTIFICATE_VALIDATION_LOG",
            "issuer": "ISSUER_DN",
            "issuerorg": null,
            "ltaentryexists": true,
            "ltaorgid": 1,
            "localizedsigcerterrorcheckmsg": null
          }
        ]
      }
    }
  ]
}

Simple Electronic Signature (SES)​

sigcheckresult: false, numberofsigs: 0 — no recognized cryptographic signature found. signerslist is empty.

{
  "verifyresult": [
    {
      "hash": "HEX_DOCUMENT_HASH",
      "sigcheck": {
        "numberofsigs": 0,
        "numberofsimplesigs": 0,
        "allsigsvalid": false,
        "allsigsqual": false,
        "allsigsusequalcert": false,
        "sigcheckresult": false,
        "allsigsltvenabled": false,
        "allsigsseal": false,
        "allsigcertsineidastrustedlist": false,
        "signerslist": []
      }
    }
  ]
}

Common Errors​

  • 400: invalid payload format (for example malformed hash or signature input)
  • 401: missing or invalid bearer token on protected endpoints
  • 403: token is valid but missing required permissions
  • 5xx: upstream verification or platform error