---
title: "Required & optional fields for a stamp combination"
method: GET
path: "/states/{code}/requirements"
tags: ["Reference data"]
---

# Required & optional fields for a stamp combination

`GET /states/{code}/requirements`

## Request

- Base URL: `https://esahayak.io/api/v1`
- URL: `https://esahayak.io/api/v1/states/{code}/requirements`
- Auth: HTTP bearer

Machine-readable required/optional-field spec for a (state, article, denomination, category) combination — the discovery counterpart to POST /stamp-orders/validate. `articleCode`, `denomination` and `category` are optional; when supplied, conditional rules (payerGender over ₹500, second-party-not-applicable, etc.) resolve to concrete `required` booleans instead of `requiredWhen` rules. The fields marked `required` here are exactly what /validate and /create reject when blank.

## Path parameters

- `code` string, required

## Query parameters

- `articleCode` string
- `denomination` number
- `category` 'e_stamp' | 'traditional_stamp'

## Response `200`

Resolved requirement spec.

- StampRequirements: Required & optional field spec for a stamp combination (GET /states/{code}/requirements). Discovery counterpart to /stamp-orders/validate — fields marked `required` here are exactly what /validate + /create reject when blank.
  - `state` object, required
    - `code` string
    - `name` string
    - `active` boolean
    - `categoriesSupported` string[]
    - `minAmount` number, nullable
    - `maxAmount` number, nullable
    - `amountMultipleOf` number, nullable: The state sells stamps only in whole multiples of this face value (₹), e.g. 10 for Uttar Pradesh — ₹100 or ₹110, never ₹101. Null when any whole amount is accepted. Off-step denominations fail /validate + /create with AMOUNT_NOT_MULTIPLE.
  - `category` 'e_stamp' | 'traditional_stamp', required
  - `article` object, nullable
    - `code` string
    - `description` string, nullable
    - `valid` boolean
    - `minimumAmount` number, nullable
    - `allowedAmounts` number[], nullable
    - `isSecondPartyNA` boolean
  - `denomination` object
    - `provided` number, nullable
    - `min` number, nullable: Effective minimum = max(state min, article minimum).
    - `max` number, nullable: State maximum (null = uncapped).
    - `allowedAmounts` number[], nullable
    - `multipleOf` number, nullable: The denomination must be a whole multiple of this (₹), e.g. 10 for Uttar Pradesh. Null = no step.
  - `fields` FieldRequirement[], required
    - `field` string, required
    - `required` boolean, required: True when the bulk API rejects the order if this field is blank for the requested inputs.
    - `requiredWhen` string: The rule that makes this field required, when it could not be resolved to a boolean (e.g. denomination not supplied).
    - `recommended` boolean: Not hard-rejected by the bulk API, but the state/provider expects it.
    - `allowedValues` string[]
    - `valueValidated` boolean: The value is validated against a catalogue when provided.
    - `discoverVia` string: Endpoint that lists valid values for this field.
    - `enforcedByBulkApi` boolean, required
    - `note` string
  - `limits` object
    - `maxStampsPerRequest` integer
    - `maxQuantityPerLine` integer
    - `maxStampsPerAccountPerDay` integer, nullable
  - `preflight` object: Account-level gates enforced only at POST /stamp-orders (not surfaced by /validate).
    - `idempotencyKeyRequired` boolean
    - `requiresSufficientWalletBalance` boolean
  - `meta` object
    - `hasCatalogue` boolean
    - `payerGenderRequiredAboveAmount` number

## Other responses

- `401`: Missing / invalid / expired / revoked key
- `404`: Not found (workspace + is_test scoped)

## Changes

- **2026-11-03** `cca124862a3e`: 2 info
  - added the optional property `denomination/multipleOf` to the response with the `200` status
  - added the optional property `state/amountMultipleOf` to the response with the `200` status

[Operation history](https://skmtc.dev/esahayak/apis/esahayak-stamp-api/changes/states/:code/requirements/get.md)

---

[API](https://skmtc.dev/esahayak/apis/esahayak-stamp-api.md) - [All operations](https://skmtc.dev/esahayak/apis/esahayak-stamp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/esahayak/apis/esahayak-stamp-api/revisions/cca124862a3e?raw)