PFX Sign

Endpoint Overview

POST /api/v1/esign/pfx-sign

Description

The PFX Digital Signature API enables automated, one-time digital signing of PDF documents using PFX/PKCS#12 certificate files. This endpoint allows you to digitally sign documents with cryptographic certificates in a single operation, ensuring document authenticity, integrity, and non-repudiation. The API supports multi-page signing with customizable signature positions and provides a streamlined one-time signing process that generates a cryptographically secure signed document.

This API is designed for businesses that need to implement legally compliant digital signature workflows without requiring manual intervention. It accepts a PDF file and a PFX certificate file, applies digital signatures at specified positions in one execution, and returns a securely signed document accessible via a pre-signed URL. The entire signing process completes in a single API call, making it efficient for high-volume document processing.

Key Benefits

One-Time Signing Process: Complete document signing in a single API call without multiple steps or callbacks

Automated Signing Workflow: Eliminate manual signature processes with programmatic PFX-based digital signing

Flexible Positioning: Place signatures at precise coordinates across multiple pages of your PDF documents

Cryptographic Security: Leverage industry-standard PFX/PKCS#12 certificates for legally binding digital signatures

Use Cases

Financial Services

Enterprise & HR

Legal & Compliance

Automated signing of loan agreements, account opening forms, and investment documents

Bulk processing of credit card applications and insurance policies

Digital execution of trading agreements and financial disclosures

Secure signing of mortgage documents and financial statements

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 YOUR_JWT_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 authentication (format: `Bearer YOUR_JWT_TOKEN`)
Content-Type	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
sign_type	string	Yes	Type of signature. Must be set to `"pfx"` for PFX certificate signing
file_id	string	Yes	Unique identifier of the PDF file to be signed (Obtained from the eSign Upload API)
pfx_id	string	Yes	Unique identifier of the PFX certificate file (Obtained from the eSign Upload API)
config	object	No	Configuration object for signature customization
config.reason	string	No	Reason for signing the document
config.positions	object	No	Object defining signature positions on specific pages. Keys are page numbers (as strings), values are arrays of position objects
config.positions.{page}.x	number	No	X-coordinate for signature placement on the specified page
config.positions.{page}.y	number	No	Y-coordinate for signature placement on the specified page
prefill_options	object	No	Pre-filled user information for the signing process
prefill_options.full_name	string	No	Full name of the signer
prefill_options.mobile_number	string	No	Mobile number of the signer
prefill_options.user_email	string	No	Email address of the signer

Example Request

{
    "sign_type": "pfx",
    "file_id": "files_koKsXuqleqLxsBRvQxffe",
    "pfx_id": "files_SbhOGrbgOsgjsDepfyod",
    "config": {
        "reason": "Test Sign",
        "positions": {
            "1": [
                {
                    "x": 40,
                    "y": 20
                }
            ],
            "2": [
                {
                    "x": 100,
                    "y": 50
                }
            ]
        }
    },
    "prefill_options": {
        "full_name": "Rahul",
        "mobile_number": "9876541271",
        "user_email": "rahul@gmail.com"
    }
}

Process Response

Response Parameters

Parameter	Type	Description
success	boolean	Indicates whether the signing operation was successful
status_code	number	HTTP status code of the response (200 for success)
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the message (e.g., `"success"`)
data	object	Container object for response data
data.client_id	string	Unique identifier for the signing session (e.g., `"esign_aaorqRheIkmypzpubRCi"`)
data.file_id	string	Identifier of the original file that was signed
data.url	string	Pre-signed S3 URL for downloading the signed PDF document (valid for limited time)

Example Successful Response

{
    "data": {
        "client_id": "esign_aaorqRheIkmypzpubRCi",
        "file_id": "files_koKsXuqleqLxsBRvQxffe",
        "url": "https://surepass-esign.s3.amazonaws.com/esign_aaorqRheIkmypzpubRCi_signed_1761635359214251.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KKKE%2F20251028%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251028T070919Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=da7829915d5b83c19ad00c9accfad5f91526b49a23fced5be72943"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Authentication

Invalid File ID

Invalid Request Body

Server Error

{
    "success": false,
    "status_code": 401,
    "message": "Unauthorized - Invalid or expired token",
    "message_code": "unauthorized"
}

The JWT Bearer token is missing, invalid, or expired. Regenerate your token and retry the request.

Integration Best Practices

Security Recommendations

Secure Token Storage: Never expose JWT tokens in client-side code or version control. Store tokens securely on your backend server

PFX Certificate Protection: Protect PFX certificate files with strong passwords and store them securely. Never share certificates in public repositories

URL Expiration Handling: The signed document URL expires after a limited time (typically 10 minutes). Download and store the signed document immediately after receiving the response

HTTPS Only: Always use HTTPS when making API calls to protect sensitive data in transit

Environment Separation: Use separate API tokens for sandbox and production environments. Never use production credentials in development

Rate Limiting: Implement retry logic with exponential backoff to handle rate limits gracefully

User Experience Guidelines

File Upload Validation: Validate PDF files and PFX certificates before uploading to ensure they meet format requirements

Progress Indicators: Display loading states during the signing process, as signature generation may take several seconds for large documents

Error Messaging: Provide clear, user-friendly error messages when signing fails, including guidance on how to resolve common issues

Immediate Download: Prompt users to download the signed document immediately, as the URL expires quickly

Signature Verification: Allow users to verify the digital signature after download using PDF readers that support certificate validation

Audit Trail: Maintain logs of signing operations including timestamps, user information, and document identifiers for compliance purposes

Code Samples

cURL

Python

Node.js

Related APIs

File Upload API: Upload PDF documents and PFX certificate files before signing

eSign Status API: Check the status and retrieve details of completed signing operations

Aadhaar eSign API: Alternative signing method using Aadhaar-based authentication for Indian citizens

Document Verification API: Verify the authenticity and integrity of digitally signed documents

Compliance and Legal Considerations

Legal Validity: Digital signatures created using PFX certificates are legally binding in most jurisdictions when properly implemented. Ensure your PFX certificates are issued by trusted Certificate Authorities (CAs) for maximum legal recognition.

Data Privacy: This API processes personal information (name, email, mobile number) which may be subject to data protection regulations like GDPR, CCPA, or India's Digital Personal Data Protection Act. Ensure you have appropriate consent and legal basis for processing user data.

Document Retention: Maintain secure archives of signed documents and audit logs for compliance with industry-specific retention requirements (typically 3-7 years for financial and legal documents).

Certificate Management: Regularly review and renew PFX certificates before expiration. Expired certificates may invalidate signatures and cause compliance issues.

Audit Requirements: The API provides client_id for each signing operation. Maintain comprehensive audit trails linking these identifiers to business processes for regulatory compliance and dispute resolution.

Industry Standards: This API supports PDF signatures compliant with ISO 32000 (PDF specification) and can be configured to meet requirements for various standards including PAdES (PDF Advanced Electronic Signatures).

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/esign/pfx-sign' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "sign_type": "pfx", "file_id": "{{pfx_file_client_id}}", "pfx_id": "{{pfx_client_id}}", "config": { "reason": "Test Sign", "positions": { "1": [ { "x": 40, "y": 20 } ], "2": [ { "x": 100, "y": 50 } ] } }, "prefill_options": { "full_name": "Rahul", "mobile_number": "9876541231", "user_email": "rahul@gmail.com" } }'

{ "data": { "client_id": "esign_aaorqRheIkmypzpubRCi", "file_id": "files_koKsXuqleqLxsBRvQxoA", "url": "https://surepass-esign.s3.amazonaws.com/esign_aaorqRheIkmypzpubRCi_signed_1761635359214251.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20251028%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251028T070919Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=da782" }, "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