Signature Verification

Endpoint Overview

POST /api/v1/pdf/utils/signature-verification

Description

The PDF Signature Verification API provides comprehensive digital signature analysis and validation for PDF documents. This powerful endpoint analyzes uploaded PDF files to verify the authenticity, integrity, and validity of digital signatures, providing detailed information about signers, certificates, and signature properties.

The API performs deep analysis of PDF signatures including certificate chain validation, signature algorithm verification, timestamp analysis, and comprehensive metadata extraction. It supports various signature formats including Adobe PKCS#7 detached signatures and provides detailed information about certificate policies, key usage, and revocation status.

Key Benefits

Comprehensive Signature Analysis: Validates digital signatures with detailed certificate chain analysis and cryptographic verification

Multi-format Support: Supports various PDF signature formats including Adobe PKCS#7 detached signatures

Certificate Validation: Performs thorough certificate validation including issuer verification and policy analysis

Detailed Metadata Extraction: Provides extensive signature metadata including signer information, timestamps, and signature properties

Use Cases

Legal & Compliance

Financial Services

Healthcare & Education

Contract Verification: Validate digital signatures on legal contracts and agreements

Document Authenticity: Ensure document integrity for compliance and audit purposes

Legal Evidence: Verify signature validity for court proceedings and legal documentation

Regulatory Compliance: Meet industry standards for document signature verification

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication (JWT)
Content-Type	Yes	Must be set to `multipart/form-data`

Request Body

Parameter	Type	Required	Description
pdf_file	file	Yes	PDF document to be analyzed for signature verification. Supports standard PDF formats with digital signatures

Example Request

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container for all verification results
data.client_id	string	Unique identifier for the verification request
data.verified	boolean	Overall verification status of the PDF signatures
data.verification_fail_reason	string/null	Reason for verification failure, null if successful
data.invalid_pdf	boolean	Indicates if the PDF format is invalid
data.pdf_corrupted	boolean	Indicates if the PDF file is corrupted
data.pdf_encrypted	boolean	Indicates if the PDF is password protected
data.signed	boolean	Indicates if the PDF contains digital signatures
data.signature_data	list	Array of detailed signature information objects
status_code	integer	HTTP status code of the response
success	boolean	Indicates if the API call was successful
message	string	Response message
message_code	string	Machine-readable message code

Example Successful Response

{
    "data": {
        "client_id": "pdf_signature_verification_kzHxzrhiRVJsuQfMXmZb",
        "verified": true,
        "verification_fail_reason": null,
        "invalid_pdf": false,
        "pdf_corrupted": false,
        "pdf_encrypted": false,
        "signed": true,
        "signature_data": [
            {
                "page_no": "1",
                "signed_on": "2023-01-27",
                "digest_algorithm": "SHA256",
                "encryption_algorithm": "RSA",
                "filter_sub_type": "/adbe.pkcs7.detached",
                "signer_name": "Rahul Kumar",
                "email": "rahul.kumar@example.com",
                "signature_type": "approval",
                "signature_field": "Signature0001",
                "signer_cert_issuer": "CN=Dummy eSign CA, OU=Certifying Authority, O=Dummy Solutions Pvt. Ltd., C=IN",
                "signer_cert_subject": "ST=Karnataka, OID.2.5.4.17=560001, OID.2.5.4.45=#03230044445555666777889900AABBCCDDEEFF00, OID.2.5.4.20=\"D/placeholderPhone=xxxxx\", OID.2.5.4.65=abcdef1234567890, CN=Rahul Kumar, O=Personal, C=IN",
                "signer_cert_serial_number": "999999888888777777666666555555444444333333222222111111",
                "signer_cert_type": "ekyc_cert_single_factor",
                "signer_cert_display_text": "PAN eKYC Certificate issued by Dummy Solutions Pvt. Ltd.",
                "valid_signature": true,
                "covers_whole_document": true,
                "signature_visible": true,
                "ocsp_verifiable": false,
                "crl_verifiable": false,
                "fill_in_allowed": true,
                "annotations_allowed": true,
                "is_time_stamped": false,
                "cert_valid_against_keystore": false,
                "certificate_policy": {
                    "policy_id": [
                        "2.16.356.100.2.4.1"
                    ],
                    "policy_data": [
                        {
                            "policy_id": "2.16.356.100.2.4.1",
                            "qualifier_id": "1.3.6.1.5.5.7.2.1",
                            "qualifier_type": "cps",
                            "cps_uri": "https://www.dummy-signature.example/cps",
                            "notice_reference_organization": "",
                            "notice_reference_notice_number": [],
                            "display_text": ""
                        }
                    ]
                },
                "subject_alt_name": [
                    {
                        "type": "rc822_name",
                        "value": "rahul.kumar@example.com"
                    }
                ],
                "cert_chain_details": [
                    {
                        "cert_version": "3",
                        "serial_number": "999999888888777777666666555555444444333333222222111111",
                        "not_before": "2023-01-27T07:30:43",
                        "not_after": "2023-01-27T07:59:43",
                        "sign_algo_name": "SHA256WITHRSA",
                        "sig_algo_oid": "1.2.840.113549.1.1.11",
                        "cert_type": "X.509",
                        "key_usage": [
                            "digitalSignature",
                            "nonRepudiation"
                        ],
                        "subject_alternative_names": [
                            "rahul.kumar@example.com"
                        ],
                        "subject": {
                            "PSEUDONYM": "abcdef1234567890abcdef1234567890",
                            "ST": "Karnataka",
                            "O": "Personal",
                            "TELEPHONENUMBER": "D/placeholderPhone=XXXXXX",
                            "CN": "Rahul Kumar",
                            "C": "IN",
                            "POSTALCODE": "560001",
                            "UNIQUEIDENTIFIER": "#UNIQUEIDDUMMY12345"
                        },
                        "issuer": {
                            "CN": "Dummy eSign CA",
                            "C": "IN",
                            "OU": "Certifying Authority",
                            "O": "Dummy Solutions Pvt. Ltd."
                        },
                        "extended_key_usage": [],
                        "issuer_alternative_names": []
                    }
                ],
                "location": "Bengaluru, Karnataka",
                "reason": "Document approval",
                "contact": "rahul.kumar@example.com",
                "revoked": null
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Sinature Verification failed

Invalid PDF

{
    "status_code": 422,
    "success": false,
    "message": "PDF Signature Verification Failed",
    "message_code": "verification_failed"
}

Returned when the signature verification failed.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely and implement proper token refresh mechanisms

File Validation: Validate file types and sizes before uploading to prevent malicious file uploads

Data Sanitization: Sanitize all response data before displaying in user interfaces

Certificate Chain Analysis: Always verify the complete certificate chain for comprehensive validation

Revocation Checking: Implement additional OCSP/CRL checking for enhanced security validation

User Experience Guidelines

Progress Indicators: Show upload progress and verification status to users during processing

Clear Error Messages: Display user-friendly error messages for different failure scenarios

Results Visualization: Present signature verification results in an easily understandable format

Mobile Optimization: Ensure file upload functionality works smoothly on mobile devices

Timeout Handling: Implement appropriate timeouts for large file uploads and processing

Code Samples

cURL

Python

Node.js

Related APIs

PDF Document Processing APIs: Additional PDF utilities for extraction, conversion, and analysis of PDF documents and their metadata.

Digital Certificate Validation APIs: Comprehensive certificate validation services for verifying digital certificates and certificate authorities.

Document Authentication APIs: Advanced document verification services for various document types including images, scanned documents, and digital files.

Compliance and Legal Considerations

Data Privacy: Ensure uploaded PDF documents are handled in compliance with applicable data protection regulations (GDPR, CCPA, etc.). Documents are processed securely and not stored permanently on Surepass servers.

Legal Validity: While this API provides technical verification of digital signatures, legal validity may depend on jurisdiction-specific regulations and the certificate authority's accreditation status.

Certificate Authority Trust: The verification results depend on the trust chain of the certificate authorities. Ensure that the certificate authorities used are recognized and trusted in your jurisdiction.

Audit Requirements: For compliance purposes, maintain audit trails of signature verification requests and results, especially for legally significant documents.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

{ "data": { "client_id": "pdf_signature_verification_kzHxzrhiRVJsuQfMXmZb", "verified": true, "verification_fail_reason": null, "invalid_pdf": false, "pdf_corrupted": false, "pdf_encrypted": false, "signed": true, "signature_data": [ { "page_no": "1", "signed_on": "2023-01-27", "digest_algorithm": "SHA256", "encryption_algorithm": "RSA", "filter_sub_type": "/adbe.pkcs7.detached", "signer_name": "Rahul Kumar", "email": "rahul.kumar@example.com", "signature_type": "approval", "signature_field": "Signature0001", "signer_cert_issuer": "CN=Dummy eSign CA, OU=Certifying Authority, O=Dummy Solutions Pvt. Ltd., C=IN", "signer_cert_subject": "ST=Karnataka, OID.2.5.4.17=560001, OID.2.5.4.45=#03230044445555666777889900AABBCCDDEEFF00, OID.2.5.4.20=\"D/placeholderPhone=xxxxx\", OID.2.5.4.65=abcdef1234567890, CN=Rahul Kumar, O=Personal, C=IN", "signer_cert_serial_number": "999999888888777777666666555555444444333333222222111111", "signer_cert_type": "ekyc_cert_single_factor", "signer_cert_display_text": "PAN eKYC Certificate issued by Dummy Solutions Pvt. Ltd.", "valid_signature": true, "covers_whole_document": true, "signature_visible": true, "ocsp_verifiable": false, "crl_verifiable": false, "fill_in_allowed": true, "annotations_allowed": true, "is_time_stamped": false, "cert_valid_against_keystore": false, "certificate_policy": { "policy_id": [ "2.16.356.100.2.4.1" ], "policy_data": [ { "policy_id": "2.16.356.100.2.4.1", "qualifier_id": "1.3.6.1.5.5.7.2.1", "qualifier_type": "cps", "cps_uri": "https://www.dummy-signature.example/cps", "notice_reference_organization": "", "notice_reference_notice_number": [], "display_text": "" }, { "policy_id": "2.16.356.100.2.4.1", "qualifier_id": "1.3.6.1.5.5.7.2.2", "qualifier_type": "unotice", "display_text": "PAN eKYC Certificate issued by Dummy Solutions Pvt. Ltd.", "cps_uri": "", "notice_reference_organization": "", "notice_reference_notice_number": [] } ] }, "subject_alt_name": [ { "type": "rc822_name", "value": "rahul.kumar@example.com" } ], "cert_chain_details": [ { "cert_version": "3", "serial_number": "999999888888777777666666555555444444333333222222111111", "not_before": "2023-01-27T07:30:43", "not_after": "2023-01-27T07:59:43", "sign_algo_name": "SHA256WITHRSA", "sig_algo_oid": "1.2.840.113549.1.1.11", "cert_type": "X.509", "key_usage": [ "digitalSignature", "nonRepudiation" ], "subject_alternative_names": [ "rahul.kumar@example.com" ], "subject": { "PSEUDONYM": "abcdef1234567890abcdef1234567890", "ST": "Karnataka", "O": "Personal", "TELEPHONENUMBER": "D/placeholderPhone=XXXXXX", "CN": "Rahul Kumar", "C": "IN", "POSTALCODE": "560001", "UNIQUEIDENTIFIER": "#UNIQUEIDDUMMY12345" }, "issuer": { "CN": "Dummy eSign CA", "C": "IN", "OU": "Certifying Authority", "O": "Dummy Solutions Pvt. Ltd." }, "extended_key_usage": [], "issuer_alternative_names": [] }, { "cert_version": "3", "serial_number": "2222333344445555666677778888999900001111222233334444", "not_before": "2020-05-06T15:10:58", "not_after": "2030-03-05T06:30:00", "sign_algo_name": "SHA256WITHRSA", "sig_algo_oid": "1.2.840.113549.1.1.11", "cert_type": "X.509", "key_usage": [ "keyCertSign", "cRLSign" ], "subject": { "C": "IN", "OU": "Certifying Authority", "O": "Dummy Solutions Pvt. Ltd.", "CN": "Dummy eSign CA" }, "issuer": { "CN": "Root Dummy CA", "O": "Dummy Root", "OU": "PKI", "C": "IN" }, "extended_key_usage": [], "subject_alternative_names": [], "issuer_alternative_names": [] }, { "cert_version": "3", "serial_number": "3333444455556666777788889999000011112222333344445555", "not_before": "2020-05-06T15:10:58", "not_after": "2030-05-06T15:10:58", "sign_algo_name": "SHA256WITHRSA", "sig_algo_oid": "1.2.840.113549.1.1.11", "cert_type": "X.509", "key_usage": [ "keyCertSign", "cRLSign" ], "subject": { "C": "IN", "CN": "Root Dummy CA", "OU": "PKI", "O": "Dummy Root" }, "issuer": { "CN": "Root Dummy CA", "C": "IN", "OU": "PKI", "O": "Dummy Root" }, "extended_key_usage": [], "subject_alternative_names": [], "issuer_alternative_names": [] } ], "signer_alternative_name": "", "location": "Bengaluru, Karnataka", "reason": "Document approval", "contact": "rahul.kumar@example.com", "time_stamp_serial_number": "", "tsa_name": "", "timestamp_policy": "", "revoked": null } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses