Skip to content
Handbid Developers

GET /v3/auction/{auctionId}/gram-recipients — bidder-safe gram recipient search

GET
/v3/auction/{auctionId}/gram-recipients
 
curl --request GET \
  --url 'https://api-ha-prod-p8.handbid.dev/v3/auction/33934/gram-recipients?q=jan&limit=20&offset=0' \
  --header 'Authorization: Bearer <token>'

The Events gram picker’s recipient search (HAN-3276), restored after SEC-38 closed GET /organization/contacts to managers. The organization is never taken from the client: it is derived from the caller’s canonical registration in {auctionId} (one no-leak query — an unknown auction and a non-participant both answer 404 not_found “Auction not found.”). Population: the organization’s authorized, live, e-mail-bearing contacts whose first name, last name, e-mail or null-safe full name STARTS with q (escaped prefix; no substring walk). Disclosure: id, name (null-safe, may be "") and emailMasked (j***@c***.com) only — never the raw e-mail, phone, company or userId. Bare v3 body (no envelope). Ordered lastName, firstName, id; totalCount is constant across pages.

Auth: required (bearer; feeds the participant gate and the auctionGramRecipients limiter, 30/min).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
auctionId
required
integer
Example 
33934

Query Parameters

Section titled “Query Parameters ”
q
required
string
>= 3 characters <= 64 characters

Search prefix, 3–64 characters after trim; matched case-insensitively at the start of first name, last name, e-mail or the full name.

Example 
jan
limit
integer
default: 20 >= 1 <= 50

Page size, canonical unsigned decimal only (+5, 05, 1e1, 10.5 → 400). Default 20, max 50.

offset
integer
0

Canonical unsigned decimal only. Default 0.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Matching recipients (first page) and the total.

Media type application/json
object
recipients
required
Array<object>
object
id
required
integer
name
required

Null-safe display name; "" when the contact has no first or last name.

string
emailMasked
required

j***@c***.com; *** when the stored e-mail has no @.

string
totalCount
required
integer
Example 
{
  "recipients": [
    {
      "id": 123,
      "name": "Jane Smith",
      "emailMasked": "j***@c***.com"
    }
  ],
  "totalCount": 1
}

400

Section titled “400 ”

validation_error — q shorter than 3 / longer than 64, a bracketed array, or a non-canonical limit/offset.

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example generated
{
  "error": "example",
  "message": "example",
  "retryAfter": 1
}

401

Section titled “401 ”

No or invalid bearer.

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example generated
{
  "error": "example",
  "message": "example",
  "retryAfter": 1
}

404

Section titled “404 ”

not_found “Auction not found.” — unknown auction OR the caller is not a registered participant of it (indistinguishable by design).

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example generated
{
  "error": "example",
  "message": "example",
  "retryAfter": 1
}

429

Section titled “429 ”

Rate limited (rate_limited); retryAfter seconds.

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example generated
{
  "error": "example",
  "message": "example",
  "retryAfter": 1
}