List Stamps

Endpoint Overview

GET /api/v1/stamper/list-stamps

Description

This endpoint retrieves a comprehensive list of all e-stamps associated with your account. E-stamps are digital versions of traditional stamp papers used for legal and financial documents. The API returns detailed information about each stamp including its unique identifier, monetary value, creation date, current status, and a direct link to download the stamp PDF.

Key Benefits

Efficiently manage and track all your e-stamps in one centralized location

Instantly access e-stamp PDFs for document processing and verification

Monitor stamp status and availability in real-time

Streamline document workflows with digital stamp integration

Use Cases

Legal Services

Real Estate

Financial Services

Law firms can track and manage e-stamps for various client agreements and legal documents

Legal process outsourcing companies can automate stamp paper acquisition for contract processing

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	JWT Bearer token for authentication. Format: `Bearer <your_jwt_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

This endpoint does not require a request body as it's a GET request to retrieve all stamps associated with the authenticated account.

Process Response

Response Parameters

Parameter	Type	Description
data	Array	List of stamp objects containing detailed information about each stamp
data[].client_id	String	Unique identifier for the client associated with the stamp
data[].stamp_id	String	Unique identifier for the stamp
data[].created_at	String	ISO 8601 timestamp indicating when the stamp was created
data[].amount	Number	The monetary value of the stamp in INR
data[].amount_added	Number	The amount that was added to create this stamp
data[].state	String	The Indian state for which the stamp is valid
data[].status	String	Current status of the stamp (e.g., "available", "used")
data[].on_hold	Boolean	Indicates if the stamp is currently on hold
data[].link	String	Temporary URL to download the e-stamp PDF (valid for a limited time)
status_code	Number	HTTP status code of the response
success	Boolean	Indicates if the API request was successful
message	String	Human-readable message describing the result
message_code	String	Machine-readable code representing the result

Example Successful Response

{
    "data": [
        {
            "client_id": "stamp_SSFpoLGpgLjMHirdgqyd",
            "stamp_id": "stamp_SSFpoLGpgLjMHirdgqyd",
            "created_at": "2024-04-05T21:42:47.536000",
            "amount": 100,
            "amount_added": 100,
            "state": "Maharashtra",
            "status": "available",
            "on_hold": false,
            "link": "https://surepass-esign.s3.amazonaws.com/vishal.rathore/stamper/stamp_SSFpoLGpgLjMHirdgqyd/stamp_1712353367449898.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20240405%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20240405T214249Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=a07f1a0ce0b420bbee5d2c341d439235fcb8dac2227c718e1c4aa73ee045a222"
        },
        {
            "client_id": "stamp_houVgQfAvaijGNlWOyEi",
            "stamp_id": "stamp_houVgQfAvaijGNlWOyEi",
            "created_at": "2024-04-05T21:39:34.053000",
            "amount": 500,
            "amount_added": 500,
            "state": "Maharashtra",
            "status": "available",
            "on_hold": false,
            "link": "https://surepass-esign.s3.amazonaws.com/vishal.rathore/stamper/stamp_houVgQfAvaijGNlWOyEi/stamp_1712353173955622.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20240405%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20240405T214249Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=8f1b0f5298512c41bf654185819d5a9bf09ee5fe1e653ddc90fecb19eeca9420"
        }
    ],
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Server Error

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

This error occurs when the JWT token is missing, invalid, or expired. Ensure you're using a valid token and that it hasn't expired.

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

Download and store e-stamp PDFs securely with appropriate access controls

Implement proper error handling to prevent sensitive information exposure

User Experience Guidelines

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

Implement pagination in your UI when displaying large numbers of stamps

Provide clear visual indicators for stamp status (available, used, on hold)

Include timestamp information in a user-friendly format (e.g., relative time)

Code Samples

cURL

Python

Node.js

Related APIs

Create Stamp - Creates a new e-stamp with specified amount and state

Get Stamp Details - Retrieves detailed information about a specific stamp

Update Stamp Status - Changes the status of an existing stamp

Download Stamp - Generates a direct download link for a stamp PDF

Compliance and Legal Considerations

E-stamps are regulated by state governments in India. Each state may have different regulations regarding stamp duty and usage. Ensure compliance with the specific state regulations where the e-stamp will be used. The validity and acceptance of e-stamps may vary across different legal and financial institutions.

{ "data": [ { "client_id": "stamp_SSFpoLGpgLjMHirdgqyd", "stamp_id": "stamp_SSFpoLGpgLjMHirdgqyd", "created_at": "2024-04-05T21:42:47.536000", "amount": 100, "amount_added": 100, "state": "Maharashtra", "status": "available", "on_hold": false, "link": "https://surepass-esign.s3.amazonaws.com/vishal.rathore/stamper/stamp_SSFpoLGpgLjMHirdgqyd/stamp_1712353367449898.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20240405%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20240405T214249Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=a07f1a0ce0b420bbee5d2c341d439235fcb8dac2227c718e1c4aa73ee045a222" }, { "client_id": "stamp_houVgQfAvaijGNlWOyEi", "stamp_id": "stamp_houVgQfAvaijGNlWOyEi", "created_at": "2024-04-05T21:39:34.053000", "amount": 500, "amount_added": 500, "state": "Maharashtra", "status": "available", "on_hold": false, "link": "https://surepass-esign.s3.amazonaws.com/vishal.rathore/stamper/stamp_houVgQfAvaijGNlWOyEi/stamp_1712353173955622.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAY5K3QRM5FYWPQJEB%2F20240405%2Fap-south-1%2Fs3%2Faws4_request&X-Amz-Date=20240405T214249Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=8f1b0f5298512c41bf654185819d5a9bf09ee5fe1e653ddc90fecb19eeca9420" } ], "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 ********************

List Stamps

List Stamps#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

List Stamps

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples