API docs by Redocly

Validation and Conversion Service API (1.2.0)

Download OpenAPI specification:

Skribble Engineering: info@skribble.com URL: https://skribble.com License: Apache 2.0 Terms of Service

This API documentation describes the publicly available Validation and Conversion Service of Skribble.

Access

Endpoints for authentication, authorization, and user access management.

Sign in with username and API key to receive a JWT access token

Authorizations:
None
Request Body schema:
required
username
required
string

Your API key name

api-key
required
string

Your API key secret

Responses

Request samples

Content type
{
  • "username": "api_demo_xxx",
  • "api-key": "your_secret_here"
}

Response samples

Content type
text/plain
eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSld...

Validation

Endpoints to validate documents, data formats, and signatures.

Validate a digitally signed content

Validate signatures in digitally signed content, such as a PDF or XML file. A validation ID {id} is returned that can be used to call additional endpoints. The content to be validated is provided in the request body and is not retained within our service. The maximum request or file size is 50MB. Request parameters can be used to set optional parameters to control the validation

Authorizations:
bearerAuth
query Parameters
quality
string
Enum: "SES" "AES" "QES"

Optional flag specifying the minimum signature quality required (SES, AES, QES).

longTermValidation
boolean

Optional flag indicating whether the signature must be long-term valid.

legislation
string
Enum: "WORLD" "CH" "EU" "CH_EU"

Optional flag specifying the legislation to comply with (WORLD, CH, EU, CH_EU).

infos
Array of strings
Items Enum: "validation" "format" "signer"

Optional flag to request additional information, such as validation, format, or signer details.

rejectVisualDifferences
boolean

Optional flag to specify if visual differences should be rejected. If 'true', validation will fail due to visual differences; if 'false' or not provided, visual differences will not cause validation to fail.

rejectUndefinedChanges
boolean

Optional flag to specify if undefined changes should be rejected. If 'true', validation will fail due to undefined changes; if 'false' or not provided, undefined changes will not cause validation to fail.

Request Body schema:
required

Content can be sent directly as a file or base64-encoded in a JSON object

content
required
string <binary>

File content to validate (PDF or XML)

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
Example
{
  • "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "valid": true,
  • "signatures": 1,
  • "validSignatures": 1,
  • "quality": "QES",
  • "legislation": "CH",
  • "longTermValidation": true,
  • "visualDifferences": false,
  • "undefinedChanges": false
}

Validate a digital signature

Validate digital signatures such as CMS and CAdES without providing the associated signed content. A validation ID {id} is returned that can be used to call additional endpoints. The signature to be validated is provided in the request body. Query parameters can be used to set optional parameters to control the validation.

Authorizations:
bearerAuth
query Parameters
quality
string
Enum: "SES" "AES" "QES"

Optional flag specifying the minimum signature quality required (SES, AES, QES).

longTermValidation
boolean

Optional flag indicating whether the signature must be long-term valid.

legislation
string
Enum: "WORLD" "CH" "EU" "CH_EU"

Optional flag specifying the legislation to comply with (WORLD, CH, EU, CH_EU).

infos
Array of strings
Items Enum: "validation" "format" "signer"

Optional flag to request additional information, such as validation, format, or signer details.

Request Body schema:
required

Content can be sent directly as a file or base64-encoded in a JSON object

content
required
string <binary>

File content to validate (PDF or XML)

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
Example
{
  • "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "valid": true,
  • "signatures": 1,
  • "validSignatures": 1,
  • "quality": "QES",
  • "legislation": "CH",
  • "longTermValidation": true
}

Validate a digital certificate [ROADMAP]

Validate a digital certificate outside of its use within signatures. A validation ID {id} is returned that can be used to call additional endpoints. The content to be validated is provided in the request body.

Authorizations:
bearerAuth
Request Body schema:
required

Content can be sent directly as a file or base64-encoded in a JSON object

content
required
string <binary>

File content to validate (PDF or XML)

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "valid": true
}

Deletes the validation

Deletes the corresponding resource identified by {id}, universal for all validation resources. Any resource that is not manually deleted will be automatically deleted after 10 minutes.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

The 'id' provided by the validate operation

Responses

Additional Information

Endpoints providing extra metadata or supplementary details for documents.

Get additional information about the validation itself. Refer to ETSI EN 319 102-1 for the indications and sub-indications that may be encountered.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

The 'id' provided by the validate operation

Responses

Response samples

Content type
application/json
{
  • "indication": "TOTAL-FAILED",
  • "subIndication": "HASH_FAILURE",
  • "details": [
    ]
}

Get additional information about the signers of a validation

Additional information about the people who signed the document. The query parameter is the id from the validation endpoint.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

The 'id' provided by the validate operation

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get additional information about the document format

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

The 'id' provided by the validate operation

Responses

Response samples

Content type
application/json
Example
{
  • "fileType": "PDF",
  • "producer": "Acrobat Distiller 6.0 (Windows)"
}

Reports

Endpoints for generating, retrieving, and managing reports related to document processing.

Skribble validation report

Get the digitally signed Skribble validation report as PDF. The report is generated once per validation ID, language and ETSI attachment flag, then cached — subsequent requests with the same parameters are served from cache and not billed. Optionally attach the ETSI TS 119 102-2 XML validation report as an embedded file in the PDF.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

The 'id' provided by the validate operation

query Parameters
lang
string
Default: "en"
Enum: "en" "de" "fr"

Language of the validation report

attachETSIReport
boolean
Default: false

Attach the ETSI TS 119 102-2 XML validation report as a file attachment to the PDF. When enabled, the XML report is embedded in the PDF and a paperclip annotation is added on the last page. This registers additional usage for the ETSI report endpoint.

Responses

ETSI TS 119 102-2 validation report

Get the ETSI TS 119 102-2 signature validation report as a XML

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "3fa85f64-5717-4562-b3fc-2c963f66afa6"

The 'id' provided by the validate operation

Responses

Tooling

Utility endpoints and tools that assist with document handling or integration.

Upload document for processing

Upload a document to be used in the tooling process. A process ID {id} is returned which can be used to call additional endpoints. If not already a PDF, the uploaded document will be converted into one. The maximum request or file size is 50MB.

Authorizations:
bearerAuth
Request Body schema:
required

Content can be sent directly as a file or base64-encoded in a JSON object

content
required
string <binary>

File content to upload for tooling processing

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "id": "1cbd5761-1429-437d-89c1-d8eacc49bf36",
  • "name": "Sample File.pdf",
  • "properties": {
    },
  • "permissions": {
    },
  • "metadata": {
    }
}

Check document PDF conformance

Checks the document against a specific set of PDF conformance criteria and guidelines. Can be called multiple times to get current status and results; if relevant changes have been made to the document with other tools, it will process the document again. If the status '423 Locked' is returned it can be recalled with some delay.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "1cbd5761-1429-437d-89c1-d8eacc49bf36"

The 'id' provided by the tooling upload operation

query Parameters
conform
required
string
Default: "claimed"
Enum: "claimed" "pdfa-1b" "pdfa-1a" "pdfa-2b" "pdfa-2u" "pdfa-2a" "pdfa-3b" "pdfa-3u" "pdfa-3a"

PDF Conformance

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "conformance": "pdfa-2b",
  • "claimedConformance": "pdfa-2b",
  • "recommendedConformance": "pdfa-3a"
}

Conform document

Convert the document to a specific PDF conformance. Can be called multiple times to get current status and results; if relevant changes have been made to the document with other tools, it will process the document again. If the process status is 'pending', '423 Locked' is returned and it can be recalled with some delay.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "1cbd5761-1429-437d-89c1-d8eacc49bf36"

The 'id' provided by the tooling upload operation

query Parameters
conform
required
string
Default: "recommendedConformance"
Enum: "recommendedConformance" "pdfa-1b" "pdfa-1a" "pdfa-2b" "pdfa-2u" "pdfa-2a" "pdfa-3b" "pdfa-3u" "pdfa-3a"

PDF Conformance

allowdowngrade
required
boolean
Default: true

Allows conformance downgrade in case of conversion error

force
boolean

Forces process despite canConvert or canCompress state

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "conformance": "pdfa-3a",
  • "downgraded": false,
  • "claimedConformance": "pdfa-2b"
}

Compress document

Compress the document for a specific purpose. For best size and compliance, this should be done before any /convert. Can be called multiple times to get current status and results; if relevant changes have been made to the document with other tools, it will process the document again. If '423 Locked' is returned it can be recalled with some delay.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "1cbd5761-1429-437d-89c1-d8eacc49bf36"

The 'id' provided by the tooling upload operation

query Parameters
optimise
required
string
Default: "size"
Enum: "archive" "print" "size" "web"

PDF Optimisation

force
boolean

Forces process despite canConvert or canCompress state

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "optimisation": "size",
  • "claimedConformance": "pdf-1.5",
  • "pages": 12,
  • "originalSize": 907128,
  • "newSize": 228161,
  • "compressionRatio": 3.975824,
  • "spaceSaving": 0.7484798176
}

Spot document for signature relevant elements

Spots and detects document elements such as fields, signatures, and positions using tags and artificial intelligence. After detection, the document is updated and fields and tags are removed while maintaining current PDF compliance. Can be called multiple times to get current status and results; if relevant changes have been made to the document with other tools, it will process the document again. If the process status is 'pending', '423 Locked' is returned and it can be recalled with some delay.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "1cbd5761-1429-437d-89c1-d8eacc49bf36"

The 'id' provided by the tooling upload operation

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "results": {
    }
}

Download processed document

Download the processed document with the changes and enhancements made according to the specified processing steps. If the status '423 Locked' is returned it can be recalled with some delay.

Authorizations:
bearerAuth
path Parameters
id
required
string <uuid>
Default: "1cbd5761-1429-437d-89c1-d8eacc49bf36"

The 'id' provided by the tooling upload operation

Responses

Delete processed document

Terminates all running processes on the document and deletes all associated content. This action occurs automatically after 10 minutes if not explicitly invoked.

Authorizations:
NonebearerAuth
path Parameters
id
required
string <uuid>
Default: "1cbd5761-1429-437d-89c1-d8eacc49bf36"

The 'id' provided by the tooling upload operation

Responses

Billing and Credits

Endpoints for managing account credits, billing information, and payment operations.

Credits information

Get the list of credit usage information associated with specific endpoints

Authorizations:
None

Responses

Response samples

Content type
application/json
{
  • "validFrom": "2024-05-30T13:45:00Z",
  • "consumptions": [
    ]
}

Current credit usage

Get credit usage list and details for current billing period

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "period": "20240528",
  • "usage": [
    ],
  • "requests": 2,
  • "credits": 4
}

Invoiced credit details

Get invoiced credit details for the most recent billing period or a specified time period

Authorizations:
bearerAuth
query Parameters
period
string

Format YYYY, YYYYMM, YYYYMMDD is supported. If not specified the last invoiced period is used by default

Responses

Response samples

Content type
application/json
{
  • "period": "20240528",
  • "usage": [
    ],
  • "requests": 2,
  • "credits": 4
}