Esign Upload

Endpoint Overview

POST /api/v1/files/esign/upload

Description

The E-Sign Upload API enables developers to securely upload documents to Surepass's e-signature platform for digital signing workflows. This endpoint accepts document files (such as PDFs) and prepares them for electronic signature processes, making it an essential component of any digital document signing integration.

This API handles the initial file upload stage of the e-signature workflow, validating and storing documents in a secure environment. It supports password-protected files, ensuring that sensitive documents can be uploaded without compromising security. Upon successful upload, the API returns unique identifiers that can be used in subsequent e-signature operations.

Key Benefits

Secure Document Handling: Upload sensitive documents with password protection support for enhanced security

Seamless E-Signature Integration: Prepares documents for immediate use in digital signature workflows

Fast Processing: Quick file validation and upload confirmation with unique file identifiers

Multi-Format Support: Accepts various document formats commonly used in business operations

Use Cases

Financial Services

Human Resources

Legal & Compliance

Upload loan agreements and financial contracts for customer e-signature

Process KYC documents requiring authorized signatures from customers

Handle insurance policy documents that need digital approval

Manage investment documents requiring secure signature workflows

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 (format: `Bearer YOUR_JWT_TOKEN`)
Content-Type	Yes	Must be `multipart/form-data` for file upload

Request Body

Parameter	Type	Required	Description
file	File	Yes	The document file to be uploaded for e-signature (e.g., PDF, DOC, PFX)
file_name	String	Yes	The name of the file being uploaded, including the file extension
password	String	No	Password for PFX file

Example Request

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object for response data
data.client_id	String	Unique identifier for the client associated with the uploaded file
data.file_id	String	Unique identifier for the uploaded file, used in subsequent e-signature operations
data.uploaded	Boolean	Indicates whether the file was successfully uploaded (true/false)
status_code	Integer	HTTP status code of the response (200 for success)
success	Boolean	Indicates whether the API request was successful
message	String	Human-readable message describing the result
message_code	String	Machine-readable code for the result status

Example Successful Response

{
    "data": {
        "client_id": "files_koKsXuqleqLxsBRvQxoA",
        "file_id": "files_koKsXuqleqLxsBRvQxoA",
        "uploaded": true
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

File Size Limit

{
    "success": false,
    "status_code": 401,
    "message": "Unauthorized access",
    "message_code": "unauthorized"
}

This error occurs when the JWT token is missing, invalid, or expired. Verify your authentication credentials and generate a new token if necessary.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely and never expose them in client-side code or version control

Use HTTPS: Always use HTTPS endpoints to encrypt data in transit

Password Handling: When uploading password-protected files, ensure passwords are transmitted securely and never logged

File Validation: Validate file types and sizes on the client side before uploading to reduce unnecessary API calls

Token Rotation: Implement token refresh mechanisms to maintain security without service interruption

Environment Separation: Use separate tokens for sandbox and production environments to prevent accidental data mixing

User Experience Guidelines

Progress Indicators: Display upload progress to users, especially for large files

Clear Error Messages: Translate technical error codes into user-friendly messages

File Preview: Allow users to preview or verify files before upload to reduce errors

Format Guidance: Clearly communicate supported file formats and size limits to users

Retry Logic: Implement automatic retry with exponential backoff for transient network failures

Success Confirmation: Provide clear confirmation when files are successfully uploaded with next steps

Code Samples

cURL

Python

Node.js

Related APIs

E-Sign Document Send API: Send uploaded documents to recipients for electronic signature

E-Sign Status Check API: Monitor the signing status of documents sent for e-signature

E-Sign Document Download API: Retrieve signed documents after completion of the signing process

File Delete API: Remove uploaded files from the system when no longer needed

Compliance and Legal Considerations

When implementing this API, ensure compliance with electronic signature regulations in your jurisdiction, including eIDAS (EU), ESIGN Act (USA), and IT Act (India). Maintain audit trails of all file uploads and implement appropriate data retention policies. Password-protected files must be handled in accordance with data protection regulations such as GDPR and local privacy laws. Ensure that uploaded documents do not contain sensitive personal information unless proper consent and security measures are in place. Organizations should establish clear policies for document retention, deletion, and access control to maintain regulatory compliance.

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/files/esign/upload' \ --header 'Authorization: Bearer <token>' \ --form 'file_name="sample.pdf"' \ --form 'file=@"/Users/karanjeetsingh/Downloads/fred.pfx"' \ --form 'password="apples"'

{ "data": { "client_id": "files_koKsXuqleqLxsBRvQxoA", "file_id": "files_koKsXuqleqLxsBRvQxoA", "uploaded": true }, "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