Surepass
Stamps

List stamp orders

View as Markdown
GET
/api/v1/stamps/list

List procurement orders for the authenticated user, paginated.

When filtering by status=pending, matching orders are returned with an empty stamps array (pending stamps are not yet materialized as instances), while status_counts.pending reflects the pending count.

Authorization

bearerAuth
AuthorizationBearer <token>

Bearer token authentication — paste your access token below.

In: header

Query Parameters

page*integer

Page number.

size*integer

Page size.

client_id?string

Filter by order client ID.

state_code?string

Filter by state code.

article_id?string

Filter by article ID. Requires state_code.

status?string

Filter by stamp instance status.

Value in

  • "pending"
  • "available"
  • "reserved"
  • "used"
  • "rejected"

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/stamps/list?page=0&size=0"
{  "data": {    "items": [      {        "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,        "status_counts": {          "pending": 0,          "available": 1,          "reserved": 0,          "used": 0,          "rejected": 0        },        "stamps": [          {            "stamp_id": "stamp_inst_vPqJLShuVXRtStskqsCw",            "status": "available"          }        ]      }    ],    "has_next": true  },  "status_code": 200,  "message": "Success",  "success": true}

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.

Download stamp PDF GET

Get the vendor-provided download URL for a completed stamp PDF. PDF bytes are not streamed through the API — the response contains a short-lived signed URL. Pass the stamp **instance** ID (`stamps[].stamp_id` from order-status or list), not the order ID.