Upload PDF via Link

Endpoint Overview

POST /api/v1/esign/upload-pdf

Description

This endpoint allows you to pre-upload a PDF document for electronic signature (eSign) processing by providing a URL to the PDF file. The API fetches the PDF from the specified URL and prepares it for subsequent eSign operations. This is the first step in the eSign workflow, enabling you to prepare documents before initiating the signature process.

Key Benefits

Streamlined document preparation for eSign workflows

Support for remote PDF files without requiring local storage

Simple integration with existing document management systems

Reduces client-side processing by handling file retrieval on the server

Use Cases

Financial Services

Legal

Human Resources

Pre-upload loan agreements for customer signature

Prepare account opening documents for digital onboarding

Upload insurance policy documents for customer approval

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.io

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Your unique client identifier provided by Surepass
link	String	Yes	A publicly accessible URL pointing to the PDF file to be uploaded

Example Request

{
    "client_id": "{{client_id}}",
    "link": "https://www.aeee.in/wp-content/uploads/2020/08/Sample-pdf.pdf"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.uploaded	Boolean	Indicates whether the file was successfully uploaded (true) or not (false)
status_code	Integer	HTTP status code of the response
message_code	String	A code indicating the result of the operation
message	String	A human-readable message describing the result
success	Boolean	Indicates whether the overall operation was successful

Example Successful Response

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

Possible Error Responses

Invalid URL

Authentication Error

Server Error

{
    "data": {
        "uploaded": false
    },
    "status_code": 400,
    "message_code": "invalid_url",
    "message": "The provided URL is invalid or inaccessible",
    "success": false
}

The URL provided is either malformed, not publicly accessible, or does not point to a valid PDF file.

Integration Best Practices

Security Recommendations

Ensure PDF URLs are served over HTTPS to maintain document confidentiality

Implement proper JWT token management with appropriate expiration times

Use temporary URLs with limited access time for sensitive documents

Validate PDF content before uploading to prevent malicious file attacks

User Experience Guidelines

Implement proper error handling to provide clear feedback to users

Add progress indicators for large PDF files during the upload process

Verify document accessibility before initiating the upload process

Implement retry mechanisms for temporary network failures

Code Samples

cURL

Python

Node.js

Related APIs

Create eSign Request: Create a new electronic signature request using the uploaded PDF

Check eSign Status: Verify the status of an electronic signature request

Download Signed Document: Retrieve the final signed PDF document

Compliance and Legal Considerations

When using this API for document signing, ensure compliance with local electronic signature laws such as eSign Act (USA), eIDAS (EU), or IT Act (India). Documents containing personal information must be handled in accordance with data protection regulations like GDPR or similar local laws. Ensure you have proper consent before processing documents containing personal information.

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/upload-pdf' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "{{client_id}}", "link": "https://www.aeee.in/wp-content/uploads/2020/08/Sample-pdf.pdf" }'

Upload PDF via Link

Upload PDF via Link#

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

Upload PDF via Link

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples