Get Upload Link for eSign Document

Endpoint Overview

POST /api/v1/esign/get-upload-link

Description

This endpoint generates a pre-signed URL that allows you to securely upload PDF documents to Surepass's eSign service. The generated URL provides temporary, authenticated access to an AWS S3 bucket where the document will be stored for electronic signature processing. This eliminates the need to handle document storage and security yourself.

Key Benefits

Secure document upload directly to AWS S3 without managing storage infrastructure

Pre-authenticated URLs with temporary access for enhanced security

Simplified integration with Surepass's eSign workflow

Automatic document association with the specified client

Use Cases

Financial Services

Insurance

HR & Recruitment

Generate upload links for loan agreements requiring customer signatures

Enable secure upload of account opening documents for digital signing

Streamline mortgage application document processing

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	Unique identifier of the client for whom the document is being uploaded

Example Request

{
    "client_id": "{{client_id}}"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the upload link details
data.link_generated	Boolean	Indicates whether the upload link was successfully generated
data.url	String	The AWS S3 URL where the PDF should be uploaded
data.fields	Object	AWS S3 form fields required for the upload
data.fields.key	String	The unique key/filename for the document in S3
data.fields.x-amz-algorithm	String	AWS signature algorithm used
data.fields.x-amz-credential	String	AWS credential used for signing
data.fields.x-amz-date	String	Timestamp of when the signature was created
data.fields.policy	String	Base64-encoded policy document
data.fields.x-amz-signature	String	The signature for the policy document
status_code	Integer	HTTP status code of the response
message_code	String	Short code indicating the result of the operation
message	String	Human-readable description of the result
success	Boolean	Overall success status of the API call

Example Successful Response

{
    "data": {
        "link_generated": true,
        "url": "https://esign.s3.amazonaws.com/",
        "fields": {
            "key": "esign_axyXXyJxaohmpadfsadsfadsfadsga754.40323.pdf",
            "x-amz-algorithm": "AWS4-HMAC-SHA256",
            "x-amz-credential": "AKIAY5K3Qadfadsfadsgadsgadguest",
            "x-amz-date": "20210913T131234Z",
            "policy": "eyJleHBpcmF0aW9uIjogadsfasdfadsgadgaeyJ4LWFtei1kYXRladsfadsfaNFoifV19",
            "x-amz-signature": "9fea3bf7bbc17dadsgshadhadgasdgadsf7321b1af27bd1392dfc08"
        }
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Link generated successfully",
    "success": true
}

Possible Error Responses

Invalid Client ID

Authentication Error

{
    "data": null,
    "status_code": 400,
    "message_code": "invalid_client_id",
    "message": "The provided client ID is invalid or does not exist",
    "success": false
}

This error occurs when the client_id provided doesn't exist in the system or is in an invalid format.

Integration Best Practices

Security Recommendations

Store the client_id securely and never expose it in client-side code

The pre-signed URL is temporary and should be used promptly after generation

Do not reuse the same pre-signed URL for multiple document uploads

Ensure the PDF document contains no malicious content before uploading

User Experience Guidelines

Generate the upload link just before the user is ready to upload the document

Provide clear feedback to users during the upload process

Implement proper error handling to guide users if uploads fail

Consider implementing a progress indicator for large document uploads

Code Samples

cURL

Python

Node.js

Related APIs

Get eSign Status - Retrieves the current status of an eSign document

Generate eSign Request - Creates a new eSign request for a client

Download Signed Document - Retrieves a document after it has been signed

Compliance and Legal Considerations

When using this API for document signing, ensure you comply with relevant electronic signature regulations such as eSign Act (US), eIDAS (EU), or IT Act (India). Documents uploaded should have proper consent mechanisms built in, and the signing process should maintain an audit trail for legal validity.

{ "data": { "link_generated": true, "url": "https://esign.s3.amazonaws.com/", "fields": { "key": "esign_axyXXyJxaohmpadfsadsfadsfadsga754.40323.pdf", "x-amz-algorithm": "AWS4-HMAC-SHA256", "x-amz-credential": "AKIAY5K3Qadfadsfadsgadsgadguest", "x-amz-date": "20210913T131234Z", "policy": "eyJleHBpcmF0aW9uIjogadsfasdfadsgadgaeyJ4LWFtei1kYXRladsfadsfaNFoifV19", "x-amz-signature": "9fea3bf7bbc17dadsgshadhadgasdgadsf7321b1af27bd1392dfc08" } }, "status_code": 200, "message_code": "success", "message": "Link generated successfully", "success": true }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Get Upload Link

Get Upload Link for eSign Document#

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