Validation API

Best Practices

Best practices for verifying digital signatures, processing documents, and generating compliance reports with the Skribble Validation API.

Base URLs

Production (CH): https://document-validation.skribble.com/v1
Production (DE): https://document-validation.skribble.de/v1

Validation Workflow

Basic Validation Flow

Code
Upload → Validate → Get Details → (Optional) Generate Report → Cleanup

Submit document for validation
Receive validation ID and quick assessment
Query detailed information using the validation ID
Generate reports if needed
Resources auto-cleanup after 10 minutes

Quick Validation Example

Code
# Validate a signed PDF
curl -X POST "https://document-validation.skribble.com/v1/validate/document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "'"$(base64 -i signed-document.pdf)"'"
  }'

Response:

Code
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "valid": true,
  "signatures": 2,
  "validSignatures": 2,
  "quality": "QES",
  "legislation": "CH_EU"
}

Understanding Validation Results

Key Response Fields

Field	Description
`valid`	Overall signature validity (boolean)
`signatures`	Total number of signatures found
`validSignatures`	Number of valid signatures
`quality`	Highest signature quality (SES/AES/QES)
`legislation`	Applicable legislation (CH/EU/CH-EU). Only present when `quality` is `QES`
`longTermValidation`	Whether long-term validation is preserved
`visualDifferences`	Indicates visual tampering
`undefinedChanges`	Indicates unauthorized modifications

Signature Quality Levels

Quality	Description	Trust Level
`QES`	Qualified Electronic Signature	Highest
`AES`	Advanced Electronic Signature	High
`SES`	Simple Electronic Signature	Basic

Legislation Codes

Code	Region
`CH`	Switzerland only
`EU`	European Union only
`CH_EU`	Valid in both

Legislation applies only to qualified signatures (QES). For SES and AES signatures, the response does not contain legislation. The legislation query parameter has an effect only when you also set quality=QES.

Getting Detailed Information

After validation, use the validation ID to get more details:

Validation Details

Code
GET /infos/{id}/validation

Returns detailed ETSI EN 319 102-1 compliant validation information.

Signer Information

Code
GET /infos/{id}/signers

Returns:

Signer names and contact information
Certificate details (subject, issuer, serial number)
Signature timestamps
Quality level per signature

Format Information

Code
GET /infos/{id}/format

Returns document format specifications and PDF/A conformance level.

Generating Reports

Skribble Report

Code
GET /reports/{id}/skribble?lang=en

Generates a digitally signed PDF validation report. The report is generated once per validation ID, language and ETSI attachment flag, then cached for subsequent requests.

Parameter	Type	Description
`lang`	string	Report language: `en` (default), `de`, `fr`
`attachetsi`	boolean	Embed the ETSI XML report as an attachment in the PDF

ETSI Compliance Report

Code
GET /reports/{id}/etsi

Generates an XML report compliant with the ETSI TS 119 102-2 V1.4.1 (2023-06) standard.

Resource Management

Auto-cleanup: Validation resources are automatically deleted after 10 minutes
Explicit deletion: Use DELETE /validate/{id} if you're done earlier

Performance Tips

Batch wisely: Process multiple documents in parallel when possible
Cache results: Store validation IDs if you need to query details multiple times
Use appropriate endpoints: Use /validate/signature for standalone signature validation
Size limits: Maximum document size is 50 MB