Revenue Stamp Get Stamp API

Endpoint Overview

GET /api/v1/revenue-stamp/get-stamp

Description

The Revenue Stamp Order Status API provides real-time tracking and detailed status information for previously placed revenue stamp orders. This endpoint enables businesses to monitor the processing, approval, and fulfillment status of their revenue stamp requisitions using the unique client identifier generated during order placement.

This API delivers comprehensive order intelligence including approval status, total stamps issued, available inventory, and pending quantities. It serves as a critical component for order management systems, enabling businesses to maintain accurate inventory tracking, provide customer updates, and ensure timely fulfillment of documentation requirements.

The endpoint supports automated monitoring workflows, allowing systems to poll for status updates and trigger downstream processes based on order progression. This real-time visibility helps organizations maintain compliance, optimize inventory management, and provide transparent order tracking to end users.

Key Benefits

Real-Time Status Tracking: Get instant updates on order processing status, from pending submission to final approval and delivery

Inventory Visibility: Track detailed stamp allocation including total issued, available for use, and pending quantities for precise inventory management

Audit Trail Support: Maintain comprehensive order tracking with reference IDs and historical status information for compliance and audit purposes

Automated Workflows: Enable programmatic status polling to trigger notifications, inventory updates, and fulfillment processes automatically

Use Cases

Legal & Compliance

Real Estate & Property

Financial Services

Law firms tracking revenue stamp orders for time-sensitive legal filings and court submissions with strict deadlines

Compliance departments monitoring stamp procurement status to ensure adequate inventory for regulatory documentation and audits

Legal process outsourcing companies managing multiple concurrent orders and requiring real-time visibility into stamp availability for client deliverables

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 YOUR_JWT_TOKEN`

Query Parameters

Parameter	Type	Required	Description
client_id	string	Yes	Unique client identifier returned when the revenue stamp order was initially placed. Format: `revenue_stamp_` followed by alphanumeric characters

Request Body

This endpoint does not require a request body as it uses GET method with query parameters.

Example Request

GET /api/v1/revenue-stamp/get-stamp?client_id=revenue_stamp_DcexQsOulJIcTssAKFTk

Process Response

Response Parameters

Parameter	Type	Description
data	object	Contains the complete order status and inventory information
data.client_id	string	Unique client identifier for the revenue stamp order
data.reference_id	string	Government or system-generated reference ID for the order processing and fulfillment tracking
data.quantity	integer	Total number of revenue stamps originally ordered
data.courier_address	string	Delivery address specified for the order
data.purpose	string	Stated purpose or use case for the revenue stamps
data.status	string	Current order status. Possible values: `pending`, `processing`, `approved`, `dispatched`, `delivered`, `cancelled`, `rejected`
data.total_stamps_issued	integer	Total number of stamps that have been issued and processed from this order
data.available_stamps	integer	Number of stamps currently available for use from this order
data.pending_stamps	integer	Number of stamps still pending processing or fulfillment
status_code	integer	HTTP status code indicating the result of the request
success	boolean	Indicates whether the request was successful (`true`) or failed (`false`)
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for programmatic handling

Example Successful Response

{
    "data": {
        "client_id": "revenue_stamp_ZDrtFNlinzspCelwscnZ",
        "reference_id": "revenue_stamp_recieved_lzhJZHxWdUxlWekvqqUe",
        "quantity": 3,
        "courier_address": "New Delhi",
        "purpose": "Stamp Testing",
        "status": "approved",
        "total_stamps_issued": 1,
        "available_stamps": 0,
        "pending_stamps": 2
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Client ID

Missing Parameters

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

This error occurs when the JWT Bearer token is missing, invalid, or expired. Verify your authentication credentials and generate a new token if necessary.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secret management systems. Never expose tokens in client-side code or commit them to version control

Client ID Protection: Treat client_id values as sensitive identifiers. Implement access controls to ensure users can only query orders they are authorized to view

HTTPS Only: Always use HTTPS endpoints for API communication to protect client_id and authentication tokens during transmission

Rate Limiting: Implement exponential backoff for polling operations to avoid API throttling and respect rate limits, especially for high-frequency status checks

Timeout Handling: Set appropriate request timeouts (recommended: 10-30 seconds) and implement proper error handling for network failures

User Experience Guidelines

Smart Polling Intervals: Use intelligent polling strategies - check frequently for pending orders (every 30-60 seconds) and reduce frequency for approved/delivered orders (every 5-10 minutes)

Status Visualization: Create clear visual indicators for different status values to help users quickly understand order progression

Inventory Dashboard: Display available_stamps, pending_stamps, and total_stamps_issued in a dashboard format for easy inventory management

Proactive Notifications: Trigger user notifications when status changes to critical states (approved, dispatched, delivered, rejected) to keep stakeholders informed

Reference ID Display: Show the reference_id prominently to users for government tracking and customer service inquiries

Error Recovery: Provide clear instructions when orders are not found, suggesting users verify their client_id or contact support if the issue persists

Code Samples

cURL

Python

Node.js

Related APIs

Revenue Stamp Order API: Place new revenue stamp orders by specifying quantity, delivery address, and purpose to receive a client_id for tracking

Revenue Stamp History API: Retrieve a comprehensive list of all revenue stamp orders with their current status and inventory details

Revenue Stamp Cancellation API: Cancel pending or processing orders using the client_id before stamps are issued or dispatched

Bulk Revenue Stamp Status API: Query status for multiple orders simultaneously by providing an array of client_id values for efficient batch processing

Revenue Stamp Usage API: Record and track the consumption of issued stamps for specific documents and transactions

Compliance and Legal Considerations

Status tracking and inventory management of revenue stamps involves specific compliance requirements:

Audit Trail Maintenance: Maintain complete logs of all status queries including timestamps, user identities, and accessed client_id values for compliance audits

Access Control: Implement role-based access control to ensure users can only query status for orders they are authorized to view, protecting sensitive procurement information

Data Retention: Retain status query logs and response data for the period mandated by local regulations, typically 3-7 years for government-related transactions

Reference ID Tracking: Use the reference_id provided in the response for all official correspondence and government inquiries regarding stamp orders

Inventory Reconciliation: Regularly reconcile available_stamps and pending_stamps values with physical inventory and usage records to maintain accurate accounting

Status Monitoring: Monitor orders in pending or processing status for extended periods, as delays may indicate issues requiring manual intervention or government follow-up

Privacy Compliance: Ensure courier_address and other personal information returned in status responses are handled in compliance with data protection regulations (GDPR, local privacy laws)

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": { "client_id": "revenue_stamp_ZDrtFNlinzspCelwscnZ", "reference_id": "revenue_stamp_recieved_lzhJZHxWdUxlWekvqqUe", "quantity": 3, "courier_address": "New Delhi", "purpose": "Stamp Testing", "status": "approved", "total_stamps_issued": 1, "available_stamps": 0, "pending_stamps": 2 }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Get Stamp

Revenue Stamp Get Stamp API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Query Parameters#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses