Upload PDF

Endpoint Overview

POST /

Description

This API endpoint allows you to upload PDF documents to the Surepass platform using a pre-generated upload link. The endpoint accepts parameters received from a previous "Get Upload Link" response and securely transfers the PDF document to Surepass's storage system. This endpoint is essential for document verification workflows, enabling seamless submission of identification documents, certificates, and other PDF files required for KYC (Know Your Customer) processes.

Key Benefits

Secure document transfer with pre-authenticated upload links

Streamlined document submission process for KYC workflows

Automatic integration with Surepass document verification systems

Reliable confirmation of successful document uploads

Use Cases

Financial Services

Healthcare

Employment Verification

Upload customer identification documents for account opening processes

Submit loan application supporting documentation

Transfer signed agreements and contracts for 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.io

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT token
Content-Type	Yes	Must be set to `multipart/form-data` for file uploads

Request Body

Parameter	Type	Required	Description
file	File	Yes	The PDF document to be uploaded
key	String	Yes	The unique key received from the Get Upload Link response
AWSAccessKeyId	String	Yes	AWS access key ID received from the Get Upload Link response
policy	String	Yes	Upload policy received from the Get Upload Link response
signature	String	Yes	Signature for upload verification received from the Get Upload Link response
x-amz-security-token	String	Yes	Security token received from the Get Upload Link response

Example Request

# This is a multipart/form-data request with the following form fields:
file: [Binary PDF file data]
key: "documents/user123/passport.pdf"
AWSAccessKeyId: "AKIAIOSFODNN7EXAMPLE"
policy: "eyJleHBpcmF0aW9uIjoiMjAyMy0xMi0zMVQwMDowMDowMFoiLCJjb..."
signature: "qKNkVRrZ+qPzxNYOtm+qHg9F4ck="
x-amz-security-token: "IQoJb3JpZ2luX2VjEHgaCXVzLWVhc3QtMSJHMEU..."

Process Response

Response Parameters

Parameter	Type	Description
status	String	Status of the upload operation (success/failure)
message	String	Descriptive message about the upload result
document_id	String	Unique identifier for the uploaded document
timestamp	String	Timestamp of when the document was uploaded

Example Successful Response

{
  "status": "success",
  "message": "Document uploaded successfully",
  "document_id": "doc_12345abcde",
  "timestamp": "2023-07-15T14:32:21Z"
}

Possible Error Responses

Authentication Error

Invalid Parameters

File Error

{
  "status": "error",
  "error_code": "AUTH_FAILED",
  "message": "Invalid or expired authentication token"
}

This error occurs when the JWT token is invalid, expired, or missing.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration

Validate PDF files on the client-side before uploading to improve user experience

Use HTTPS for all API communications to ensure data security

User Experience Guidelines

Implement progress indicators for file uploads to provide feedback to users

Add file size validation before upload to prevent errors

Provide clear error messages to users when uploads fail

Implement retry mechanisms for failed uploads due to network issues

Code Samples

cURL

Python

Node.js

Related APIs

Get Upload Link API: Generates pre-signed URLs and parameters for document uploads

Document Verification API: Verifies uploaded documents for authenticity and data extraction

Document Status API: Checks the status of previously uploaded documents

Compliance and Legal Considerations

When uploading documents containing personal information, ensure compliance with data protection regulations such as GDPR, CCPA, or other applicable regional privacy laws. Documents should be transmitted securely, and appropriate consent should be obtained from individuals before uploading their personal documents. Retention periods for documents should align with regulatory requirements and your organization's data retention policies.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/esign/upload-pdf' \ --form 'x-amz-signature="{{signature}}"' \ --form 'x-amz-date="{{date}}"' \ --form 'x-amz-credential="{{credentials}}"' \ --form 'key="{{upload_key}}"' \ --form 'policy="{{policy}}"' \ --form 'x-amz-algorithmm="{{algorithm}}"' \ --form 'file=@""'

Upload PDF

Upload PDF#

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

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples