Get Estamp Stats

Endpoint Overview

GET /api/v1/stamper-v2/stats

Description

This endpoint retrieves comprehensive statistics about your e-stamps, categorized by their current status. It provides a detailed breakdown of all stamps in your inventory, including their monetary values, state codes, article IDs, and quantities. This information is essential for inventory management, financial reconciliation, and planning stamp-related operations.

Key Benefits

Get real-time visibility into your entire e-stamp inventory across all status categories

Track pending, available, and on-hold stamps for better resource planning

Monitor stamp quantities and values to optimize inventory management

Easily reconcile e-stamp assets for financial reporting

Use Cases

Financial Services

Government Services

Legal Services

Track digital stamp inventory for financial document processing

Reconcile available stamp values for accounting and audit purposes

Monitor pending stamps to forecast upcoming document processing capacity

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 format
Content-Type	Yes	Application/json

Request Body

This endpoint does not require a request body.

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the stamp statistics categorized by status
data.pending	Array	List of stamps that are in pending status
data.available	Array	List of stamps that are available for use
data.on_hold	Array	List of stamps that are currently on hold
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable status message
message_code	String	Machine-readable status code

Stats Object Structure

Each item in the pending, available, and on_hold arrays contains:

Parameter	Type	Description
state	String	Status code of the stamp (e.g., "DL")
amount	Integer	Monetary value of the stamp
article_id	String	Stamp Article ID
count	Integer	Quantity of stamps with these specifications

Example Successful Response

{
    "data": {
        "pending": [],
        "available": [
            {
                "state": "DL",
                "amount": 20,
                "article_id": "22128",
                "count": 1
            },
            {
                "state": "DL",
                "amount": 40,
                "article_id": "22128",
                "count": 21
            }
        ],
        "on_hold": [
            {
                "state": "DL",
                "amount": 20,
                "article_id": "22128",
                "count": 1
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Server Error

{
    "status_code": 401,
    "success": false,
    "message": "Authentication failed. Invalid token provided.",
    "message_code": "authentication_failed"
}

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

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 gracefully

Use HTTPS for all API communications to ensure data security

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Cache stamp statistics when appropriate to reduce API calls and improve performance

Implement proper loading states when fetching stamp data

Display stamp statistics in an organized, categorized manner for easy comprehension

Provide visual indicators for low stamp inventory to prompt timely replenishment

Code Samples

cURL

Python

Node.js

Related APIs

Purchase Estamp: Allows you to purchase new e-stamps for your inventory

Apply Estamp: Enables you to apply an e-stamp to a document

Estamp History: Provides historical data about e-stamp usage and transactions

Compliance and Legal Considerations

E-stamps are regulated digital assets that may be subject to specific legal requirements in different jurisdictions. Ensure your usage complies with local regulations regarding digital stamps, document certification, and record-keeping requirements. Proper inventory management and reconciliation may be required for audit purposes.

{ "data": { "pending": [], "available": [ { "state": "DL", "amount": 20, "article_id": "22128", "count": 1 }, { "state": "DL", "amount": 40, "article_id": "22128", "count": 21 } ], "on_hold": [ { "state": "DL", "amount": 20, "article_id": "22128", "count": 1 } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Get Stats

Get Estamp Stats#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Response Parameters#

Stats Object Structure#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses