---
title: "Signature inspection - Rest PKI Core"
description: "Open a signed PDF, CMS/CAdES or XML file with PUT api/signature-inspection: list its signers and, with validate = true, validate their signatures against a security context."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-inspection"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# Signature inspection - Rest PKI Core

The signature inspection API opens a signed file and returns its signers: who signed, when, with which certificate and signature policy.
Optionally, it also validates each signature. One route serves the three formats that [Rest PKI Core](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core) signs:

| File | Signatures |
| --- | --- |
| PDF | PAdES |
| CMS (`.p7s`, `.p7m`) | CAdES, attached or detached |
| XML | XmlDSig and XAdES |

> **Tip**
>
> From this point on we'll describe calls to Rest PKI Core. Make sure you've read the [Get Started](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started) article to be able to keep up. The
> application's API key needs a role that allows inspecting signatures, such as **Worker** (see [Choosing roles](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started#roles)).

## Inspecting a file

Send the signed file in the `file` field, as a [file reference](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/file-referencing):

```text
PUT {endpoint}/api/signature-inspection
{
	"file": {
		"content": "JVBERi0xLjcK...",
		"name": "contract.pdf",
		"mimeType": "application/pdf"
	},
	"validate": true,
	"securityContextId": "201856ce-273c-4058-a872-8937bd547d36"
}
```

Rest PKI Core tells the format by the file's MIME type: `application/pdf`, `application/xml` or `text/xml`, or a type containing `pkcs7`, such as
`application/pkcs7-signature`. When the request has no `mimeType`, Rest PKI Core takes it from the file name's extension, or from the
`Content-Type` of a file referenced by `url`. Any other type fails with `UnrecognizedSignedFileMimeType`, and a file whose type can't be found fails
with `MimeTypeRequired`.

The request has these fields:

| Field | Description |
| --- | --- |
| `file` | The signed file. Required |
| `validate` | Whether to validate the signatures. If `false`, the default, the signers are only listed |
| `securityContextId` | The [security context](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/security-contexts) that decides which certificates are trusted, when validating. If omitted, Rest PKI Core uses the subscription's default security context or, without one, the instance's. An ID that doesn't exist fails with `SecurityContextNotFound`, even without validation |
| `ignoreRevocationStatusUnknown` | When validating, accept certificates whose revocation status can't be determined. Default `false` |
| `trustUncertifiedSigningTime` | When validating, take the signing time declared by the signer as the reference date, even when no timestamp certifies it. Default `false` |
| `dataFile`, `dataHashes` | The signed data of a detached CMS signature: see [Detached CMS signatures](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-inspection#detached) |
| `extractEncapsulatedContent` | Return the content encapsulated in a CMS file. Default `false`; ignored for PDF and XML |

On Node.js, the [restpki-core-client](https://www.npmjs.com/package/restpki-core-client) library calls this route with `inspectSignature()`, and on
Python, [restpki-ng-python-client](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started#python) with `SignatureInspectionApi.api_signature_inspection_put()`. The .NET, Java and PHP
libraries have no method for it: call the route directly, as described in [Calling the API directly](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started#rest).

### Validation

With `validate = true`, Rest PKI Core validates each signature against the security context, with a basic policy for the format: PAdES basic for
PDF, CAdES-BES for CMS and XmlDSig basic for XML. The request takes no signature policy. Validation can take a few seconds or longer.

Only the first 10 signers of a file are validated. On your own instance, the limit is the `General:SignatureInspectionMaxValidations` setting.

An inspection with `validate = true` is counted as a **Signature validation** transaction, and one without as a **Signature inspection**.

### Files signed on this instance

When the file was signed on the same instance, for instance in a [signature session](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-sessions), Rest PKI Core recognizes it
and returns the signers as it stored them when the document was signed, along with the document in `document`. In that case it doesn't validate the
signatures again, and `securityContextId` is not used.

## Reading the response

An abridged response, for a PDF with one signer:

```json
{
	"success": true,
	"signers": [
		{
			"certificate": {
				"subjectName": { "commonName": "JOHN DOE:12345678901" },
				"issuerDisplayName": "AC EXAMPLE"
			},
			"signingTime": "2026-10-12T14:30:00-03:00",
			"signatureFieldName": "Signature1",
			"isDocumentTimestamp": false,
			"validationResults": {
				"passedChecks": [],
				"errors": [],
				"warnings": []
			}
		}
	],
	"document": null
}
```

| Field | Description |
| --- | --- |
| `success` | `false` only when validating a detached CMS signature without its data (see [below](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-inspection#detached)) |
| `signers` | One entry per signature. Empty if the file is not signed |
| `document` | The document, when the file was [signed on this instance](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-inspection#signed-here); otherwise `null` |
| `hasEncapsulatedContent`, `encapsulatedContentType`, `encapsulatedContent` | For a CMS file, whether it encapsulates content and of which type; with `extractEncapsulatedContent = true`, also the content, as a file reference |

Each signer has its `certificate`, the signature's `signingTime`, `signaturePolicy`, `timestamps` and `archiveTimestamps`, and, for PDFs, the
`signatureFieldName` and whether the entry is a document timestamp (`isDocumentTimestamp`). `validationResults` has the checks that passed, the
errors and the warnings, and is `null` when the signature was not validated. A signature is valid when its `validationResults` has no `errors`.

## Detached CMS signatures

A detached CMS signature (`.p7s`) doesn't contain the file it signs. To validate it, send the signed data as well, in one of two ways:

* `dataFile`: the signed file, as a file reference
* `dataHashes`: its hashes, each with `algorithm` and `value` (in Base64) or `hexValue`. Send at least the SHA-256 hash. This is the better choice for
  large files, since the file doesn't need to be sent

If you validate without sending either, the response has `success = false`, `failure = DataFileRequired` and, in `missingDataHash`, the algorithm of the hash needed.
This lets a page ask the user for the signed file only when it is needed. Without validation, the signers are listed without the data. `dataFile` and `dataHashes` are accepted only for CMS: with a PDF or an
XML file, the call fails with `DataFileNotSupported`.

## Moving from Rest PKI

On [Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki/validate-signatures), signatures are opened with one route per format, through the explorers of the client library
(`PadesSignatureExplorer`, `CadesSignatureExplorer` and `XmlSignatureExplorer`). Rest PKI Core still serves those routes (see
[Moving from Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/migrating-from-rest-pki#served-apis)). Signature inspection differs from them:

| | Rest PKI `Open` routes | Signature inspection |
| --- | --- | --- |
| **Route** | One per format: `POST Api/PadesSignatures/Open`, `Api/CadesSignatures/Open`, `Api/XmlSignatures/Open` | One for all formats: `PUT api/signature-inspection` |
| **Signature policy** | `defaultSignaturePolicyId` and `acceptableExplicitPolicies` | None: a basic policy for each format |
| **No security context given** | The signature policy decides what is trusted | The subscription's or instance's default security context |
| **Signers validated** | All on Rest PKI; the first 10 on Rest PKI Core | The first 10 |
| **Detached CMS without data** | Fails with `MissingDataHash` | `success = false`, `failure = DataFileRequired` |
| **Response** | A model per format | `signers`, the same for every format, and `document` |

To validate against a specific signature policy, keep the `Open` routes.

## See also

* [Security contexts](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/security-contexts)
* [Referencing files](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/file-referencing)
* [PDF stamps](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/pdf-stamp)