Bulk Stamp Order Summary

Endpoint Overview

POST /api/v1/stamper-v2/bulk-stamp-order-summary

Description

The Bulk Stamp Order Summary API provides a comprehensive overview of stamp orders associated with a specific client. This endpoint retrieves the current status of all stamps in a bulk order, categorizing them into three distinct states: pending, available, and failed.

This API is essential for tracking the lifecycle of stamp orders, enabling real-time monitoring of stamp generation processes, and ensuring efficient management of digital stamp inventory. Organizations can use this endpoint to verify stamp availability before performing bulk operations, monitor order completion rates, and identify any stamps that may have failed during generation.

The response provides detailed counts and individual stamp identifiers for each status category, making it easy to implement automated workflows, error handling, and reporting mechanisms.

Key Benefits

Real-Time Status Tracking: Get instant visibility into the status of all stamps in a bulk order

Efficient Inventory Management: Monitor available stamps and plan bulk operations accordingly

Proactive Error Handling: Quickly identify and address failed stamp generations

Scalable Operations: Support high-volume stamp management with organized status categorization

Use Cases

Financial Services

Healthcare

Government & Legal

Enterprise

Document Authentication: Banks and financial institutions can track stamp availability for digitally signing bulk loan documents, account opening forms, and compliance certificates

Batch Processing: Monitor stamp inventory before initiating end-of-day batch processing for thousands of transaction records

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

Example Authorization Header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

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`

Request Body

Parameter	Type	Required	Description
client_id	string	Yes	Unique identifier for the client whose bulk stamp order summary is being requested. This ID is provided when a bulk stamp order is created.

Example Request

{
    "client_id":"bulk_stamp_v2_vomMHvHneclzTL"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the stamp order summary information
data.client_id	string	The client identifier for which the summary was retrieved
data.quantity	integer	Total number of stamps in the bulk order
data.summary	object	Categorized summary of stamps by their current status
data.summary.pending	object	Information about stamps that are still being processed
data.summary.pending.count	integer	Number of stamps in pending status
data.summary.pending.stamps	array	Array of stamp IDs that are currently pending
data.summary.available	object	Information about stamps that are ready for use
data.summary.available.count	integer	Number of stamps available for use
data.summary.available.stamps	array	Array of stamp IDs that are available
data.summary.failed	object	Information about stamps that failed during generation
data.summary.failed.count	integer	Number of stamps that failed
data.summary.failed.stamps	array	Array of stamp IDs that failed
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the request was successful (true/false)
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the message

Example Successful Response

{
    "data": {
    "client_id":"bulk_stamp_v2_vomMHvKlzTPL",
    "quantity": 2,
    "summary": {
        "pending": {
            "count": 0,
            "stamps": []
        },
        "available": {
            "count": 2,
            "stamps": [
                "stamp_v2_ltIyIpbNoVxnc",
                "stamp_v2_mIaLighXQDcmgD"
            ]
        },
        "failed": {
            "count": 0,
            "stamps": []
            }
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Client ID

Validation Error

Server Error

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

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

Integration Best Practices

Security Recommendations

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

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

HTTPS Only: Always use HTTPS for API calls to ensure data encryption in transit.

Rate Limiting: Implement exponential backoff for retry logic to avoid overwhelming the API during high-volume operations.

Input Validation: Validate client_id format before making API calls to reduce unnecessary requests.

Logging: Log API requests and responses (excluding sensitive data) for audit trails and debugging purposes.

User Experience Guidelines

Polling Strategy: For pending stamps, implement intelligent polling with increasing intervals (e.g., 5s, 10s, 30s) rather than constant polling.

Progress Indicators: Display real-time progress using the count values (e.g., "2 of 5 stamps ready") to keep users informed.

Error Recovery: For failed stamps, provide clear error messages and retry options to users.

Batch Operations: Before initiating bulk operations, call this endpoint to verify sufficient available stamps.

Status Dashboard: Create a visual dashboard showing pending, available, and failed counts for better operational visibility.

Notifications: Implement webhook or notification systems to alert users when stamp generation completes or fails.

Code Samples

cURL

Python

Node.js

Java

PHP

Compliance and Legal Considerations

Data Privacy: Ensure that client_id and stamp identifiers are handled in accordance with your organization's data privacy policies and applicable regulations (GDPR, CCPA, etc.).

Audit Trails: Maintain comprehensive logs of stamp order queries for compliance and audit purposes, especially in regulated industries.

Access Control: Implement role-based access control (RBAC) to ensure only authorized personnel can query bulk stamp order summaries.

Retention Policies: Follow appropriate data retention policies for stamp records as required by your industry regulations.

Digital Signature Compliance: If stamps are used for digital signatures, ensure compliance with eIDAS (EU), IT Act 2000 (India), ESIGN Act (US), or relevant digital signature regulations in your jurisdiction.

Record Keeping: Maintain records of stamp generation, allocation, and usage for the legally required duration specific to your industry.

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-stamp-order-summary' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "bulk_stamp_v2_vomMHvHnrKlzTPRtyL" }'

{ "data": { "client_id": "bulk_stamp_v2_vomMHvHnecrlzTPRtyL", "quantity": 2, "summary": { "pending": { "count": 0, "stamps": [] }, "available": { "count": 2, "stamps": [ "stamp_v2_ltIyIpbNoVxnclqhEVey", "stamp_v2_mIaLighXQDcmgcijVceD" ] }, "failed": { "count": 0, "stamps": [] } } }, "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