Bulk Usage Report Initiate

Endpoint Overview

POST /api/v1/stamper-v2/bulk-usage-report/initiate

Description

The Bulk Usage Report Initiation API enables businesses to programmatically generate comprehensive usage reports for their bulk stamping operations. This endpoint initiates an asynchronous report generation process that compiles detailed usage statistics, transaction records, and operational metrics for a specified bulk stamping client.

When invoked, the API creates a report request that is processed in the background, allowing you to retrieve comprehensive usage data without impacting real-time operations. The report includes information about stamp requests, success rates, timestamps, and other critical metrics essential for auditing, billing, and operational monitoring.

This API is designed for high-volume operations where understanding usage patterns and maintaining detailed audit trails is crucial for business operations and compliance requirements.

Key Benefits

Asynchronous Processing: Initiate report generation without blocking your application workflow

Comprehensive Usage Tracking: Access detailed metrics and statistics for all bulk stamping operations

Audit Trail Maintenance: Maintain complete records for compliance and operational review

Scalable Reporting: Handle large volumes of data efficiently through background processing

Use Cases

Financial Services

Legal & Compliance

Enterprise Operations

Transaction Auditing: Generate periodic usage reports to audit digital stamping activities across loan documents, account opening forms, and compliance certificates

Billing Reconciliation: Track API usage for internal chargeback or cost allocation across different departments or business units

Compliance Reporting: Create audit trails for regulatory requirements by documenting all document stamping activities

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

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	The unique identifier for the bulk stamper client for which the usage report should be generated. This ID is provided when the bulk stamper client is created.

Example Request

{
    "client_id": "bulk_stamp_v2_vomMHvHnecrKlzTPRtyL"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the report initiation details
data.client_id	String	Unique identifier for the usage report request. Use this ID to check the status and retrieve the completed report.
data.bulk_stamp_client_id	String	The bulk stamper client ID for which the report was requested.
data.status	String	Current status of the report generation. Possible values: `pending`, `processing`, `completed`, `failed`
status_code	Integer	HTTP status code of the response (200 for success)
success	Boolean	Indicates whether the request was successful
message	String	Human-readable message describing the result
message_code	String	Machine-readable code for the message

Example Successful Response

{
    "data": {
        "client_id": "bulk_stamper_order_usage_report_UizlzAdTkllQnAsmqnco",
        "bulk_stamp_client_id": "bulk_stamp_v2_vomMHvHnecrKlzTPRtyL",
        "status": "pending"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Authentication

Invalid Client ID

Missing Parameters

Server Error

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

This error occurs when the JWT token is missing, invalid, or expired. Ensure you're using a valid bearer token in the Authorization header.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure credential management systems. Never hardcode tokens in your source code.

Token Rotation: Implement token refresh mechanisms to minimize the risk of token compromise. Regenerate tokens periodically according to your security policy.

HTTPS Only: Always use HTTPS for API requests to ensure data is encrypted in transit. Never make requests over unencrypted HTTP connections.

Client ID Protection: Treat client IDs as sensitive information and implement appropriate access controls to prevent unauthorized access.

Rate Limiting: Implement client-side rate limiting to avoid overwhelming the API and potentially triggering security mechanisms.

User Experience Guidelines

Asynchronous Handling: Implement polling or webhook mechanisms to check report status rather than blocking user operations. Display progress indicators to users.

Error Feedback: Provide clear, user-friendly error messages when report initiation fails. Include guidance on how to resolve common issues.

Report Scheduling: Consider implementing scheduled report generation during off-peak hours to optimize performance and resource utilization.

Status Notifications: Notify users when reports are ready for download rather than requiring them to check status manually.

Retry Logic: Implement exponential backoff retry logic for transient failures to improve reliability without overwhelming the API.

Code Samples

cURL

Python

Node.js

Related APIs

Bulk Usage Report Status Check: Check the current status of a previously initiated usage report request to determine if the report is ready for retrieval

Bulk Usage Report Download: Download the completed usage report once the status indicates completion

Bulk Stamper Client Management: Create, update, or retrieve details about bulk stamper clients

Bulk Stamping Operations: Submit and manage bulk document stamping requests

Compliance and Legal Considerations

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

Audit Requirements: Retain usage reports for the period required by applicable regulations and your organization's compliance policies.

Access Control: Implement role-based access control to ensure only authorized personnel can initiate and access usage reports.

Data Retention: Establish clear data retention policies for usage reports in accordance with legal and regulatory requirements.

API Usage Terms: Ensure your usage of this API complies with Surepass's Terms of Service and Acceptable Use Policy.

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/stamper-v2/bulk-usage-report/initiate' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "bulk_stamp_v2_vomMHvHnecrKlzTPRtyL" }'

{ "data": { "client_id": "bulk_stamper_order_usage_report_UizlzAdTkllQnAsmqnco", "bulk_stamp_client_id": "bulk_stamp_v2_vomMHvHnecrKlzTPRtyL", "status": "pending" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

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