Bulk Order Estamp

Endpoint Overview

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

Description

This endpoint allows you to place bulk orders for electronic stamp papers (eStamps) across various Indian states. eStamps are digital versions of traditional stamp papers used for legal agreements and documents. This API simplifies the process of ordering multiple stamp papers with the same specifications in a single request, making it efficient for businesses that need to process multiple agreements simultaneously.

Key Benefits

Order multiple eStamps with identical specifications in a single API call

Supports all major Indian states with their respective stamp duty regulations

Enables generic second party names for maximum reusability of stamp papers

Streamlines document processing workflows for financial and legal institutions

Use Cases

Financial Services

Legal Services

Real Estate

Bulk generation of stamp papers for loan agreements across multiple customers

Creating standardized stamp papers for credit card agreements

Processing multiple mortgage documents with identical stamp requirements

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

Request Body

Parameter	Type	Required	Description
first_party	String	Yes	Name of the first party on the stamp paper
second_party	String	Yes	Name of the second party (use generic terms like "Borrower")
state	String (Enum)	Yes	Two-letter state code where the stamp will be issued
article_id	Integer	Yes	Specific article ID for the stamp type
amount	Integer	Yes	The stamp duty amount in INR
consideration_amount	Integer	Yes	The consideration amount for the agreement
quantity	Integer	Yes	Number of identical stamps to order
description	String	Yes	Brief description of the stamp purpose

State Codes

The state parameter must be one of the following two-letter codes:

AN (Andaman and Nicobar Islands)
AP (Andhra Pradesh)
AR (Arunachal Pradesh)
AS (Assam)
BR (Bihar)
CH (Chandigarh)
CT (Chhattisgarh)
DL (Delhi)
GA (Goa)
GJ (Gujarat)
HR (Haryana)
HP (Himachal Pradesh)
JH (Jharkhand)
JK (Jammu and Kashmir)
KA (Karnataka)
KL (Kerala)
MH (Maharashtra)
ML (Meghalaya)
MN (Manipur)
MP (Madhya Pradesh)
MZ (Mizoram)
OR (Odisha)
PB (Punjab)
PY (Puducherry)
RJ (Rajasthan)
SK (Sikkim)
TG (Telangana)
TN (Tamil Nadu)
TR (Tripura)
UP (Uttar Pradesh)
UT (Uttarakhand)
WB (West Bengal)

Sandbox Limitations

In the sandbox environment, only the following combination is supported:

State: DL (Delhi)

Article ID: 22128

Example Request

{
    "first_party": "ABC Pvt Ltd",
    "second_party": "Borrower",
    "state": "DL",
    "article_id": 22128,
    "amount": 40,
    "consideration_amount": 1,
    "quantity": 2,
    "description": "Estamp"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the stamp order details
data.client_id	String	Unique identifier for the bulk stamp order
data.created_at	String	Timestamp when the order was created (ISO format)
data.amount	Integer	The stamp duty amount in INR
data.consideration_amount	Integer	The consideration amount for the agreement
data.first_party	String	Name of the first party on the stamp paper
data.second_party	String	Name of the second party
data.article_id	String	The article ID for the stamp type
data.state	String	Two-letter state code where the stamp is issued
data.quantity	Integer	Number of identical stamps ordered
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

Example Successful Response

{
    "data": {
        "client_id": "bulk_stamp_v2_qSHjxvcozLbbKjwmGVCc",
        "created_at": "2025-01-13T14:34:33.904783",
        "amount": 40,
        "consideration_amount": 1,
        "first_party": "ABC Pvt Ltd",
        "second_party": "Borrower",
        "article_id": "22128",
        "state": "DL",
        "quantity": 2
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Parameters

Authentication Error

Unsupported State/Article

{
    "status_code": 400,
    "success": false,
    "message": "Invalid parameters provided",
    "message_code": "invalid_parameters"
}

This error occurs when one or more required parameters are missing or have invalid values.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications to ensure data encryption

Rotate JWT tokens periodically and implement token expiration policies

User Experience Guidelines

Always use generic second party names to ensure stamp reusability

Implement proper validation for state codes and article IDs before making API calls

Store the client_id returned in the response for future reference and tracking

Consider implementing retry logic with exponential backoff for failed requests

Code Samples

cURL

Python

Node.js

Related APIs

Single Order Estamp API - For ordering individual stamp papers

Estamp Verification API - For verifying the authenticity of issued eStamps

Estamp Status API - For checking the current status of ordered eStamps

Compliance and Legal Considerations

eStamps are governed by the Indian Stamp Act and respective state stamp acts

Different states have different stamp duty rates and article classifications

Always ensure the correct article ID is used for the specific agreement type

The second party name should be generic to allow reuse of the stamp paper for different signatories

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/stamper-v2/bulk-order-stamp' \ --header 'Content-Type: application/json' \ --data-raw '{ "first_party": "ABC Pvt Ltd", "second_party": "Borrower", "state": "DL", "article_id": 22128, "amount": 40, "consideration_amount": 1, "quantity": 2, "description": "Estamp" }'

{ "data": { "client_id": "bulk_stamp_v2_qSHjxvcozLbbKjwmGVCc", "created_at": "2025-01-13T14:34:33.904783", "amount": 40, "consideration_amount": 1, "first_party": "ABC Pvt Ltd", "second_party": "Borrower", "article_id": "22128", "state": "DL", "quantity": 2 }, "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 ********************

Bulk Order Estamp

Bulk Order Estamp#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

State Codes#

Sandbox Limitations#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Bulk Order Estamp

Description

Use Cases

Technical Implementation

Request Headers

Request Body

State Codes

Sandbox Limitations

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples