Bulk Usage Report Download

Endpoint Overview

GET /api/v1/stamper-v2/bulk-usage-report/download

Description

The Bulk Usage Report Download API enables you to retrieve a comprehensive usage report for bulk stamper operations. This endpoint generates and provides access to a downloadable CSV file containing detailed information about stamp usage across multiple documents or transactions processed through the bulk stamper service.

When invoked, the API returns a presigned URL to download the usage report along with statistical information about the bulk operation status, including the count of pending, available, and failed stamp operations. The report provides visibility into resource consumption, operational efficiency, and helps with billing reconciliation and audit trails.

Key Benefits

Real-time Access: Get instant access to up-to-date usage reports for your bulk stamping operations

Detailed Statistics: View comprehensive stats including pending, available, and failed operations at a glance

Secure Download: Receive time-limited, secure presigned URLs for report downloads

Audit Trail: Maintain detailed records of bulk stamping activities for compliance and billing purposes

Use Cases

Financial Services

Legal & Compliance

Enterprise Operations

Generate monthly usage reports for bulk document stamping in loan processing systems

Track stamp consumption across multiple branches for cost allocation and budgeting

Create audit trails for compliance reporting and regulatory requirements

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 {JWT_TOKEN}`
Content-Type	Yes	Must be set to `application/json`

Query Parameters

Parameter	Type	Required	Description
client_id	string	Yes	Unique identifier for the bulk stamper order usage report. This is generated when a bulk usage report is requested and is used to retrieve the specific report.

Example Request

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the response data
data.client_id	string	The unique client identifier for the usage report request
data.bulk_stamp_client_id	string	The unique identifier for the associated bulk stamp operation
data.status	string	Status of the report generation (e.g., "success")
data.stats	object	Statistical information about the bulk stamping operations
data.stats.pending	integer	Number of stamp operations that are still pending
data.stats.available	integer	Number of stamp operations that are available/completed
data.stats.failed	integer	Number of stamp operations that have failed
data.link	string	Presigned S3 URL for downloading the usage report CSV file. This URL is time-limited and expires after a specific duration
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the API call was successful
message	string	Human-readable message describing the response
message_code	string	Machine-readable code for the response message

Example Successful Response

{
    "data": {
    "client_id":"bulk_stamper_order_usAdTkl",
    "bulk_stamp_client_id": "bulk_stamp_v2_vomMHvrKlzTPRtyL",
        "status": "success",
        "stats": {
            "pending": 0,
            "available": 2,
            "failed": 0
        },
        "link": "https://surepass-esign.s3.amazonaws.com/nitindabas_surepass/bulk_order_usage_report/bulk_stamper_order_usage_report_UizlzAdTkllQnAsmqnco/bulk_order_usage_report_1763705994346546.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20251121%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251121T061958Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=74949a182b6d95f1b8a054f5050108cb831a2ba86d81f9788014ee1d4854c077"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Unauthorized

Report Generation Pending

{
    "data": null,
    "status_code": 404,
    "success": false,
    "message": "Report not found",
    "message_code": "report_not_found"
}

This error occurs when the provided client_id does not correspond to any existing usage report. Verify that the client_id is correct and that the report has been generated.

Integration Best Practices

Security Recommendations

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

Token Rotation: Implement token refresh mechanisms to handle token expiration gracefully

Download Link Expiry: Download the report immediately as the presigned URL has a limited validity period (typically 10 minutes)

HTTPS Only: Always use HTTPS for API requests to ensure data transmission security

IP Whitelisting: Configure IP whitelisting for production environments to add an additional security layer

User Experience Guidelines

Polling Strategy: If the status is "pending", implement exponential backoff polling to check report status without overwhelming the API

Progress Indicators: Show users clear progress indicators when generating and downloading reports

Error Handling: Provide user-friendly error messages and actionable steps when report generation fails

Download Automation: Automatically trigger the CSV download when the link becomes available

Report Archival: Store downloaded reports locally for historical reference and offline access

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Data Privacy: Usage reports may contain sensitive information. Ensure compliance with data protection regulations (GDPR, CCPA, etc.) when storing and processing reports

Audit Requirements: Maintain usage reports for the duration required by your industry's regulatory framework

Secure Disposal: Implement secure deletion procedures for reports containing sensitive information after retention period expires

Access Control: Restrict access to usage reports to authorized personnel only and maintain access logs

Report Integrity: The presigned URLs are time-limited to ensure report integrity. Do not share download links as they expire after a short duration

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "bulk_stamper_order_usage_report_UizlzAdTkllQnAsmqnco", "bulk_stamp_client_id": "bulk_stamp_v2_vomMHvHnecrKlzTPRtyL", "status": "success", "stats": { "pending": 0, "available": 2, "failed": 0 }, "link": "https://surepass-esign.s3.amazonaws.com/bulk_order_usage_report/bulk_stamper_order_usage_report_UizlzAdTkllQnAsmqnco/bulk_order_usage_report_1763705994346546.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5KVPBYKKE%2F20251121%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20251121T061958Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=74949a182b6d95f1b8a054f5050108cb831a2ba86d81f9788014ee1d4854c077" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses