Bulk Stamp Orders List

Endpoint Overview

POST /api/v1/stamper-v2/bulk-stamp-orders-list

Description

The Bulk Stamp Orders List API enables you to retrieve a comprehensive list of all bulk stamp orders placed within a specified date range. This endpoint provides paginated access to stamp order records, including detailed information about each transaction such as parties involved, stamp duty amounts, article types, and delivery addresses.

This API is designed for businesses and organizations that need to track, audit, or manage multiple stamp paper orders efficiently. It supports date-based filtering and pagination to handle large volumes of stamp order data while maintaining optimal performance.

Key Benefits

Centralized Order Tracking: Access all your bulk stamp orders from a single endpoint with date range filtering

Comprehensive Order Details: Retrieve complete information including party details, amounts, article IDs, and delivery addresses

Efficient Pagination: Handle large datasets with built-in pagination support for optimal performance

Audit Trail Support: Maintain compliance with detailed timestamp and order information for regulatory requirements

Use Cases

Financial Services

Legal & Compliance

Real Estate & Property

Loan Documentation: Track stamp duty payments for loan agreements, mortgage documents, and security instruments

Compliance Reporting: Generate periodic reports of all stamp orders for internal audits and regulatory filings

Cost Analysis: Monitor stamp duty expenses across different states and document types for financial planning

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`

Request Body

Parameter	Type	Required	Description
page	integer	No	Page number for pagination. Default 1
start_date	string	Yes	Start date for filtering orders. Format: `YYYY-MM-DD`
end_date	string	Yes	End date for filtering orders. Format: `YYYY-MM-DD`

Example Request

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

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object for response data
data.start_date	string	Start date of the query range
data.end_date	string	End date of the query range
data.stamps	array	Array of stamp order objects
data.stamps[].client_id	string	Unique identifier for the stamp order
data.stamps[].created_at	string	Timestamp when the order was created (ISO 8601 format)
data.stamps[].amount	number	Stamp duty amount
data.stamps[].consideration_amount	number	Consideration amount for the transaction
data.stamps[].first_party	string	Name of the first party in the transaction
data.stamps[].first_party_father_name	string	Father's name of the first party
data.stamps[].first_party_address	string	Address of the first party
data.stamps[].second_party	string	Name of the second party in the transaction
data.stamps[].article_id	string	Article ID as per stamp duty regulations
data.stamps[].state	string	State code where the stamp is applicable
data.stamps[].courier_address	string	Delivery address for the stamp papers
data.stamps[].quantity	integer	Quantity of stamp papers ordered
data.pagination	object	Pagination information
data.pagination.page	integer	Current page number
data.pagination.records	integer	Number of records in the current page
data.pagination.has_next	boolean	Indicates if more pages are available
status_code	integer	HTTP status code
success	boolean	Indicates if the request was successful
message	string	Response message
message_code	string	Machine-readable message code

Example Successful Response

{
    "data": {
        "start_date": "2025-11-18",
        "end_date": "2025-11-18",
        "stamps": [
            {
                "client_id": "bulk_stamp_v2_ctfWfTZsjqRNKeBkkhWF",
                "created_at": "2025-11-18T13:41:59.868000",
                "amount": 1,
                "consideration_amount": 1,
                "first_party": "ABC Pvt Ltd",
                "first_party_father_name": "Father Name",
                "first_party_address": "Address",
                "second_party": "Borrower",
                "article_id": "2710",
                "state": "DL",
                "courier_address": "delhi",
                "quantity": 2
            },
            {
                "client_id": "bulk_stamp_v2_vomMHvHnecrKlzTPRtyL",
                "created_at": "2025-11-18T13:41:16.109000",
                "amount": 1,
                "consideration_amount": 1,
                "first_party": "ABC Pvt Ltd",
                "first_party_father_name": "Father Name",
                "first_party_address": "Address",
                "second_party": "Borrower",
                "article_id": "2710",
                "state": "DL",
                "courier_address": "delhi",
                "quantity": 2
            },
            {
                "client_id": "bulk_stamp_v2_fxmzmqznpBbzEhijlJpt",
                "created_at": "2025-11-18T12:12:20.559000",
                "amount": 1,
                "consideration_amount": 1,
                "first_party": "ABC Pvt Ltd",
                "first_party_father_name": "Father Name",
                "first_party_address": "Address",
                "second_party": "Borrower",
                "article_id": "2710",
                "state": "DL",
                "courier_address": "delhi",
                "quantity": 2
            }
        ],
        "pagination": {
            "page": 1,
            "records": 3,
            "has_next": false
        }
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Date Range

Missing Parameters

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

This error occurs when the JWT token is missing, invalid, or has 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 application code.

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

HTTPS Only: Always use HTTPS for API calls to ensure data encryption in transit, especially when dealing with sensitive party information and financial data.

Rate Limiting: Implement client-side rate limiting to avoid overwhelming the API and ensure fair usage across all clients.

Error Handling: Implement comprehensive error handling to manage authentication failures, network issues, and invalid responses gracefully.

User Experience Guidelines

Pagination Strategy: Implement infinite scroll or numbered pagination in your UI to handle large datasets efficiently and improve user experience.

Date Range Validation: Validate date ranges on the client side before making API calls to reduce unnecessary requests and improve response times.

Loading States: Display appropriate loading indicators when fetching data, especially for large date ranges that may take longer to process.

Data Caching: Cache frequently accessed date ranges to reduce API calls and improve application performance.

Empty States: Provide clear messaging when no stamp orders exist for the selected date range, guiding users to adjust their filters.

Code Samples

cURL

Python

Node.js

Compliance and Legal Considerations

Data Privacy: Ensure compliance with data protection regulations when storing or processing party information retrieved from this API. Personal data such as names, father's names, and addresses should be handled according to applicable privacy laws.

Record Retention: Maintain audit trails of all stamp order queries for compliance with financial and legal documentation requirements. Many jurisdictions require retention of stamp duty records for specified periods.

State Regulations: Be aware that stamp duty regulations vary by state in India. The article_id and state fields should be validated against current state-specific stamp duty acts and schedules.

Transaction Verification: Cross-verify stamp order details with physical stamp papers received to ensure accuracy and prevent fraud.

Tax Compliance: Stamp duty payments may have tax implications. Consult with tax professionals to ensure proper accounting and reporting of stamp duty expenses.

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

{ "data": { "start_date": "2025-11-18", "end_date": "2025-11-18", "stamps": [ { "client_id": "bulk_stamp_v2_ctfWfTZsjqRNKeBkkhWF", "created_at": "2025-11-18T13:41:59.868000", "amount": 1, "consideration_amount": 1, "first_party": "ABC Pvt Ltd", "first_party_father_name": "Father Name", "first_party_address": "Address", "second_party": "Borrower", "article_id": "2710", "state": "DL", "courier_address": "delhi", "quantity": 2 }, { "client_id": "bulk_stamp_v2_vomMHvHnecrKlzTPRtyL", "created_at": "2025-11-18T13:41:16.109000", "amount": 1, "consideration_amount": 1, "first_party": "ABC Pvt Ltd", "first_party_father_name": "Father Name", "first_party_address": "Address", "second_party": "Borrower", "article_id": "2710", "state": "DL", "courier_address": "delhi", "quantity": 2 }, { "client_id": "bulk_stamp_v2_fxmzmqznpBbzEhijlJpt", "created_at": "2025-11-18T12:12:20.559000", "amount": 1, "consideration_amount": 1, "first_party": "ABC Pvt Ltd", "first_party_father_name": "Father Name", "first_party_address": "Address", "second_party": "Borrower", "article_id": "2710", "state": "DL", "courier_address": "delhi", "quantity": 2 } ], "pagination": { "page": 1, "records": 3, "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