File Upload API

Endpoint Overview

POST /api/v1/sureparser/upload-file

Description

The File Upload API enables seamless document upload to the Sureparser platform for intelligent document parsing and data extraction. This endpoint accepts various document formats including PDFs and images, processes them through advanced OCR and AI-powered parsing engines, and returns a unique file identifier that can be used for subsequent parsing operations.

This API serves as the entry point for document digitization workflows, allowing businesses to convert physical or digital documents into structured, actionable data. The uploaded files are securely stored and processed, with the returned file_id serving as a reference for retrieving parsed results through complementary parsing endpoints.

Key Benefits

Multi-Format Support: Accepts various document formats including PDF, images (JPG, PNG), and scanned documents

Secure Processing: Files are encrypted during transmission and storage, ensuring data privacy and compliance

Fast Upload: Optimized infrastructure ensures quick file uploads with minimal latency

Seamless Integration: Simple API design enables easy integration into existing document management workflows

Use Cases

Financial Services

Healthcare

Logistics & Supply Chain

Upload customer KYC documents (PAN, Aadhaar, passport) for automated identity verification

Process loan application documents including bank statements and income proofs

Digitize insurance claim forms and supporting documents for faster claim processing

Extract data from tax documents and financial statements for compliance audits

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 JWT token for authentication. Format: `Bearer <your_jwt_token>`
Content-Type	Yes	Must be set to `multipart/form-data` for file upload

Request Body

Parameter	Type	Required	Description
file	File	Yes	The document file to be uploaded. Only PDF is supported. The file should be sent as form-data with the key name 'file'.

Example Request

Process Response

Response Parameters

Parameter	Type	Description
success	Boolean	Indicates whether the API request was successful (true) or failed (false)
status_code	Integer	HTTP status code of the response (200 for success)
message	String	Human-readable message describing the result of the operation
message_code	String	Machine-readable code for the operation result (e.g., "success")
data	Object	Container object holding the response payload
data.file_id	String	Unique identifier for the uploaded file. Use this ID for subsequent parsing operations. Format: `studio_file_<random_string>`
data.name	String	Original filename of the uploaded document

Example Successful Response

{
"data": {
"file_id": "studio_file_lyoWkhcQyExjshhzcqof",
"name": "sample.pdf"
},
"status_code": 200,
"success": true,
"message": "Success",
"message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid File Format

Missing File Parameter

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

This error occurs when the JWT token is missing, invalid, or expired. Verify that you're using the correct token for the environment (sandbox/production) and that it hasn't expired.

Integration Best Practices

Security Recommendations

Token Management: Store JWT tokens securely using environment variables or secure vaults. Never hardcode tokens in your application code.

HTTPS Only: Always use HTTPS endpoints to ensure encrypted transmission of sensitive documents.

File Validation: Implement client-side validation to check file types and sizes before uploading to reduce unnecessary API calls.

Token Rotation: Implement regular token rotation policies to minimize security risks from compromised credentials.

Access Control: Restrict API access to authorized systems and implement IP whitelisting where possible.

User Experience Guidelines

Progress Indicators: Display upload progress for large files to keep users informed during the upload process.

Error Handling: Provide clear, user-friendly error messages when uploads fail, with actionable steps for resolution.

File Preview: Show users a preview of the document before upload to confirm they're uploading the correct file.

Retry Mechanism: Implement automatic retry logic with exponential backoff for transient network failures.

File Retention: Store the returned file_id securely for future reference and parsing operations.

Code Samples

cURL

Python

Node.js

Related APIs

Parse Document API: Use the returned file_id to extract structured data from the uploaded document

Get Parsing Status API: Check the processing status of your uploaded file

Retrieve Parsed Data API: Fetch the final parsed results once processing is complete

Document Classification API: Automatically classify the uploaded document type for intelligent routing

Compliance and Legal Considerations

When using this API for document processing, ensure compliance with relevant data protection regulations such as GDPR, CCPA, and local privacy laws. Uploaded documents may contain personally identifiable information (PII) and sensitive data that require appropriate handling and storage measures. Implement data retention policies aligned with regulatory requirements and obtain necessary user consents for document processing. The API is designed to support compliance workflows, but ultimate responsibility for regulatory compliance rests with the implementing organization. Consider implementing audit logs for all file uploads to maintain compliance traceability.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Upload File

File Upload API#

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