Surepass
Stamps

Create stamp order

View as Markdown
POST
/api/v1/stamps/create-order

Create a stamp procurement order and start the background procurement workflow.

  • This call is asynchronous — a successful response does not mean stamps is populated yet. Poll GET /api/v1/stamps/order-status or GET /api/v1/stamps/list until instances become available.
  • Billing charges estamp_duty (stamp_duty_amount × quantity) plus estamp_fees (one per stamp). The request is rejected if the wallet balance is insufficient.

Authorization

bearerAuth
AuthorizationBearer <token>

Bearer token authentication — paste your access token below.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

state_code*string

Supported stamp state code.

first_party_name*string

First party name printed on the stamp.

Length1 <= length <= 200
second_party_name*string

Second party name printed on the stamp.

Length1 <= length <= 200
article_id*string

Article ID; must be valid for state_code.

Length1 <= length <= 100
stamp_duty_amount*number

Stamp duty per stamp. Must be a whole number, greater than 0 and at most 1,000,000 — fractional values are rejected.

consideration_amount*number

Consideration amount for the underlying transaction.

Range0 < value
quantity*integer

Number of stamps to procure.

Range1 <= value <= 5000
description?string

Optional order description.

Lengthlength <= 500
first_party_address?string

Optional first party address.

Length1 <= length <= 500

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/stamps/create-order" \  -H "Content-Type: application/json" \  -d '{    "state_code": "AN",    "first_party_name": "Alice Test",    "second_party_name": "Bob Test",    "article_id": "2337",    "stamp_duty_amount": 10,    "consideration_amount": 1000,    "quantity": 1  }'
{  "data": {    "user_id": "user_RQJksjuRzdhRjejyOlhEI",    "client_id": "stamp_pkHLyIzspuMWBMXizUSc",    "created_at": "2026-04-18T16:35:21.123000",    "state_code": "AN",    "first_party_name": "Alice Test",    "second_party_name": "Bob Test",    "article_id": "2337",    "stamp_duty_amount": "10",    "consideration_amount": 1000,    "description": null,    "first_party_address": null,    "quantity": 1,    "stamps": []  },  "status_code": 200,  "message": "Success",  "success": true}

List articles GET

List the supported articles for a state. Use the returned `article_id` when creating a procurement order.

Get order status GET

Get the latest state of a procurement order. Once the background workflow completes, `stamps` contains the vendor stamp instances and `status_counts` is populated. - `stamps[].stamp_id` is the public stamp **instance** ID — use it with `GET /api/v1/stamps/download-pdf` and for explicit stamp reservation in Esign initialization.