Auction List API¶

This guide documents the v2 REST contract for staff console auction listing.

Audience: frontend engineers integrating company and superadmin auction dashboards.

Related docs:

Conventions¶

All endpoints require:

Authorization: Bearer <access-token>
Content-Type: application/json

All successful responses use the standard envelope:

{
  "status": "success",
  "code": 200,
  "data": {},
  "message": "Auctions fetched successfully.",
  "error": null
}

Pagination defaults to pageNumber=1 and pageSize=10. pageSize must be between 1 and 100.

Company scope is always derived from authentication for company users. A company request cannot switch scope by sending companyId.

Endpoint Matrix¶

Method	Endpoint	Role	Scope
`GET`	`/v2/admin/auctions`	`SUPERADMIN`	All auctions, optional `companyId`.
`GET`	`/v2/companies/auctions`	`COMPANY`	Authenticated company auctions only.

Query Parameters¶

Multi-value enum filters are comma-separated.

Example:

GET /v2/admin/auctions?auctionStatus=SCHEDULED,LIVE&cycleStatus=ACTIVE

Param	Type	Notes
`pageNumber`	integer	Optional. Default `1`, minimum `1`.
`pageSize`	integer	Optional. Default `10`, maximum `100`.
`companyId`	string	Superadmin filter. Ignored for company scope and replaced with auth company ID.
`programId`	string	Filter by program ID.
`cycleId`	string	Filter by cycle ID.
`search`	string	Searches program name, chit ID, company name, and company branch. Max `100` chars.
`auctionStatus`	comma string	`SCHEDULED`, `READY`, `LIVE`, `PAUSED`, `ENDED`, `COMPLETE`, `CANCELLED`.
`cycleStatus`	comma string	Any `CycleStatus` enum value.
`auctionBidMode`	comma string	`DISCOUNT_INCREASING`, `TOTAL_VALUE_DECREASING`.
`auctionClosingMode`	comma string	`DURATION_MODE`, `CALL_MODE`.
`prebidMutabilityPolicy`	comma string	`IMMUTABLE_CANCEL_ONLY`, `MUTABLE_UNTIL_CLOSE`.
`hasPrebid`	boolean	`true` or `false`.
`allowStaffOfflineBids`	boolean	`true` or `false`.
`prebidStartFrom`, `prebidStartTo`	ISO datetime	Filter by prebid start range.
`prebidEndFrom`, `prebidEndTo`	ISO datetime	Filter by prebid end range.
`auctionStartFrom`, `auctionStartTo`	ISO datetime	Filter by live auction start range.
`endedFrom`, `endedTo`	ISO datetime	Filter by auction end range.
`createdFrom`, `createdTo`	ISO datetime	Filter by auction creation range.
`cycleNumber`	integer	Exact cycle number.
`minimumBidAmountMin`, `minimumBidAmountMax`	number	Inclusive minimum bid amount range.
`totalAmountMin`, `totalAmountMax`	number	Inclusive program total amount range.
`leadingBidAmountMin`, `leadingBidAmountMax`	number	Inclusive current leading bid amount range.
`sortField`	string	Requires `sortOrder`. Values: `auction_start_at`, `prebid_end_at`, `created_at`, `cycle_number`, `program_name`, `total_amount`, `leading_bid_amount`.
`sortOrder`	string	Requires `sortField`. Values: `asc`, `desc`.

Default sort: auction_start_at asc, with auction ID as the tie-breaker.

Response Fields¶

data contains standard pagination metadata plus auctions.

Field	Type	Notes
`auctionId`	string	Auction ID.
`cycleId`	string	Program cycle ID.
`programId`	string	Program ID.
`programName`	string	Program name.
`chitId`	string or `null`	Program chit ID.
`companyId`	string	Company user ID.
`companyName`	string or `null`	Company display name.
`companyBranch`	string or `null`	Company branch.
`cycleNumber`	number	Cycle number.
`cycleStatus`	string	Cycle status.
`auctionStatus`	string	Auction status.
`prebidPhase`	string	Derived prebid window phase: `NONE`, `OPEN`, `CLOSED`.
`hasPrebid`	boolean	Resolved auction/program prebid setting.
`auctionBidMode`	string	Resolved bid mode.
`auctionClosingMode`	string	Resolved closing mode.
`prebidStartAt`, `prebidEndAt`	ISO datetime or `null`	Prebid timing.
`auctionStartAt`	ISO datetime or `null`	Live auction start time.
`auctionDurationSeconds`	number or `null`	Live auction duration.
`auctionEndAt`	ISO datetime or `null`	Derived end time.
`closingPhase`	string or `null`	Active call phase, if call closing has started.
`closingPhaseEndsAt`	ISO datetime or `null`	Active call phase bid deadline.
`startedAt`, `pausedAt`, `endedAt`	ISO datetime or `null`	Runtime timestamps.
`minimumBidAmount`	number or `null`	Program minimum bid amount.
`totalAmount`	number or `null`	Program total amount.
`leadingBidAmount`	number or `null`	Current leading bid amount.
`bidCount`	number	Non-deleted bid count.
`activePrebidCount`	number	Active, non-deleted prebid count.
`createdAt`, `updatedAt`	ISO datetime	Auction row timestamps.

Examples¶

Admin listing live auctions for a company¶

GET /v2/admin/auctions?companyId=cmp_123&auctionStatus=LIVE&pageNumber=1&pageSize=20

Company listing upcoming scheduled auctions¶

GET /v2/companies/auctions?auctionStatus=SCHEDULED&cycleStatus=UPCOMING&sortField=auction_start_at&sortOrder=asc

Search by chit, program, company, or branch¶

GET /v2/admin/auctions?search=Auction%20Branch

Date and amount range filters¶

GET /v2/admin/auctions?auctionStartFrom=2026-08-01T00:00:00.000Z&auctionStartTo=2026-08-31T23:59:59.999Z&totalAmountMin=100000&totalAmountMax=500000

Success response¶

{
  "status": "success",
  "code": 200,
  "data": {
    "count": 1,
    "hasPreviousPage": false,
    "hasNextPage": false,
    "pageNumber": 1,
    "pageSize": 10,
    "totalPages": 1,
    "auctions": [
      {
        "auctionId": "auction-id",
        "cycleId": "cycle-id",
        "programId": "program-id",
        "programName": "Gold Chit 2026",
        "chitId": "CHIT-2026",
        "companyId": "company-id",
        "companyName": "Dichit Company",
        "companyBranch": "Kochi",
        "cycleNumber": 3,
        "cycleStatus": "ACTIVE",
        "auctionStatus": "SCHEDULED",
        "prebidPhase": "OPEN",
        "hasPrebid": true,
        "auctionBidMode": "TOTAL_VALUE_DECREASING",
        "auctionClosingMode": "DURATION_MODE",
        "prebidStartAt": "2026-08-13T09:00:00.000Z",
        "prebidEndAt": "2026-08-13T10:00:00.000Z",
        "auctionStartAt": "2026-08-13T11:00:00.000Z",
        "auctionDurationSeconds": 1800,
        "auctionEndAt": "2026-08-13T11:30:00.000Z",
        "closingPhase": null,
        "closingPhaseEndsAt": null,
        "startedAt": null,
        "pausedAt": null,
        "endedAt": null,
        "minimumBidAmount": 100,
        "totalAmount": 1000,
        "leadingBidAmount": null,
        "bidCount": 0,
        "activePrebidCount": 2,
        "createdAt": "2026-08-01T05:30:00.000Z",
        "updatedAt": "2026-08-01T05:30:00.000Z"
      }
    ]
  },
  "message": "Auctions fetched successfully.",
  "error": null
}

Validation failures return 400, including invalid enum values, invalid dates, missing sortField/sortOrder pairs, and ranges where To/Max is lower than From/Min.