List Orders

Endpoint Overview

POST https://kyc-api.surepass.io/api/v1/revenue-stamp/list-orders

Description

The List Revenue Stamp Orders API enables you to retrieve a comprehensive list of all revenue stamp orders placed within a specified date range. This endpoint provides detailed information about each order including its status, quantities, delivery details, and stamp allocation metrics. The API supports pagination to efficiently handle large datasets and allows you to track the complete lifecycle of revenue stamp orders from placement to fulfillment.

Revenue stamps are essential legal instruments used for document authentication and compliance with Indian Stamp Act requirements. This API helps organizations maintain accurate records of their stamp inventory, monitor order fulfillment, and ensure compliance with legal documentation requirements.

Key Benefits

Comprehensive Order Tracking: View complete order history with real-time status updates across pending and approved orders

Flexible Date Filtering: Query orders within any custom date range to support auditing and reconciliation needs

Detailed Stamp Metrics: Access granular data on total issued, available, and pending stamps for inventory management

Pagination Support: Efficiently retrieve large order datasets with built-in pagination controls

Use Cases

Financial Services

Legal & Compliance

Real Estate

Track revenue stamp orders for loan documentation and agreement execution

Monitor stamp inventory levels to ensure continuous availability for contract processing

Generate compliance reports for regulatory audits showing stamp usage history

Reconcile stamp purchases with accounting records for expense management

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
start_date	string	Yes	Start date for filtering orders in YYYY-MM-DD format (e.g., "2025-10-18")
end_date	string	Yes	End date for filtering orders in YYYY-MM-DD format (e.g., "2025-11-26")
page	integer	No	Page number for pagination. Default value is 1. Use for retrieving subsequent pages of results

Example Request

{
    "start_date": "2025-10-18",
    "end_date": "2025-11-26",
    "page": 1
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the response data
data.start_date	string	Echo of the requested start date filter
data.end_date	string	Echo of the requested end date filter
data.stamps	array	Array of stamp order objects matching the filter criteria
data.stamps[].client_id	string	Unique identifier for the stamp order (e.g., "revenue_stamp_FpPkPrhwg")
data.stamps[].created_at	string	ISO 8601 timestamp of when the order was created
data.stamps[].quantity	integer	Total quantity of stamps ordered
data.stamps[].courier_address	string	Delivery address for the stamp order
data.stamps[].purpose	string	Business purpose or reason for ordering stamps
data.stamps[].status	string	Current order status. Values: "pending", "approved"
data.stamps[].total_stamps_issued	integer	Total number of stamps that have been issued from this order
data.stamps[].available_stamps	integer	Number of stamps currently available for use
data.stamps[].pending_stamps	integer	Number of stamps still pending fulfillment
data.pagination	object	Pagination metadata for the result set
data.pagination.page	integer	Current page number being returned
data.pagination.records	integer	Total number of records on the current page
data.pagination.has_next	boolean	Indicates whether additional pages are available (true/false)
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the request was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the response status

Example Successful Response

{
    "data": {
        "start_date": "2025-10-18",
        "end_date": "2025-11-26",
        "stamps": [
            {
                "client_id": "revenue_stamp_FpPkPrhwg",
                "created_at": "2025-11-21T10:19:59.804000",
                "quantity": 100,
                "courier_address": "abc",
                "purpose": "Stamp Testing",
                "status": "pending",
                "total_stamps_issued": 0,
                "available_stamps": 0,
                "pending_stamps": 100
            },
            {
                "client_id": "revenue_stamp_QXkOOBrPbruhZmotmUnC",
                "created_at": "2025-11-21T09:56:28.453000",
                "quantity": 100,
                "courier_address": "abc",
                "purpose": "Stamp Testing",
                "status": "approved",
                "total_stamps_issued": 11,
                "available_stamps": 19,
                "pending_stamps": 70
            }
        ],
        "pagination": {
            "page": 1,
            "records": 16,
            "has_next": false
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Validation Error

Server Error

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

Occurs when the JWT bearer token is missing, invalid, or has expired. Regenerate your token and retry the request.

Integration Best Practices

Security Recommendations

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

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 retry logic to handle rate limiting gracefully

Access Control: Restrict API credentials to only authorized personnel and systems with legitimate business needs

User Experience Guidelines

Date Range Validation: Validate date inputs on the client side before making API calls to reduce unnecessary requests

Progressive Loading: When has_next is true, implement lazy loading or "Load More" functionality for better user experience

Status Indicators: Use clear visual indicators to distinguish between pending and approved orders in your UI

Empty States: Handle scenarios where no orders exist in the date range with helpful messaging

Error Handling: Provide user-friendly error messages that guide users on how to resolve issues

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Revenue stamps in India are governed by the Indian Stamp Act, 1899, and various state-specific stamp acts. Organizations must ensure that:

All revenue stamp purchases and usage are properly documented for audit and compliance purposes

Stamps are used only for their intended legal purposes as specified during procurement

Physical stamp inventory is securely stored and access is restricted to authorized personnel

Regular reconciliation is performed between API records and physical stamp inventory

Any discrepancies in stamp counts are reported and investigated promptly

Data retention policies comply with applicable financial and legal record-keeping requirements (typically 7 years minimum)

This API facilitates compliance by providing comprehensive audit trails and real-time visibility into stamp procurement and usage patterns.

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/revenue-stamp/list-orders' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "start_date": "2025-10-18", "end_date": "2025-11-26", "page": 1 }'

{ "data": { "start_date": "2025-10-18", "end_date": "2025-11-26", "stamps": [ { "client_id": "revenue_stamp_FpPkPrh", "created_at": "2025-11-21T10:19:59.804000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_tyaxB", "created_at": "2025-11-21T10:19:59.485000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_yPgm", "created_at": "2025-11-21T10:19:59.179000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_xMtWWQlDwqcuKuptLkdr", "created_at": "2025-11-21T10:19:58.845000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_RgMl", "created_at": "2025-11-21T10:19:58.531000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_gOdZe", "created_at": "2025-11-21T10:19:58.207000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_pwoa", "created_at": "2025-11-21T10:19:57.881000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_WYtom", "created_at": "2025-11-21T10:19:57.544000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_eujS", "created_at": "2025-11-21T10:19:57.212000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_iJYfSsR", "created_at": "2025-11-21T10:19:56.908000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_PUiS", "created_at": "2025-11-21T10:19:56.585000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_ZRSdk", "created_at": "2025-11-21T10:19:56.255000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_QMvY", "created_at": "2025-11-21T10:19:55.917000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_huuq", "created_at": "2025-11-21T10:19:55.565000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_VTRyx", "created_at": "2025-11-21T10:19:32.226000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "pending", "total_stamps_issued": 0, "available_stamps": 0, "pending_stamps": 100 }, { "client_id": "revenue_stamp_QXkOO", "created_at": "2025-11-21T09:56:28.453000", "quantity": 100, "courier_address": "abc", "purpose": "Stamp Testing", "status": "approved", "total_stamps_issued": 11, "available_stamps": 19, "pending_stamps": 70 } ], "pagination": { "page": 1, "records": 16, "has_next": false } }, "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