Quickstart

This walkthrough takes you from zero to a working integration. Every snippet is copy-pasteable against the production API. Substitute your own credentials where indicated.

1. Get a bearer token

Handbid authenticates with OAuth2 bearer tokens minted via an SMS-PIN flow. You issue three POSTs in sequence:

Email check

Tell the server which user wants in. If they exist, an SMS PIN is sent to their phone on file.

curl -X POST 'https://api-ha-prod-p8.handbid.dev/v3/auth/email-check' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "captchaToken": "<reCAPTCHA v3 token>"
  }'

The response tells you whether the user exists. If they don’t, follow POST /v3/auth/register instead.

Verify the PIN

The user reads the SMS and types it into your client. Submit the PIN plus the email to mint a token.

curl -X POST 'https://api-ha-prod-p8.handbid.dev/v3/auth/verify-pin' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "pin": "482910"
  }'

On success you get back:

{
  "accessToken": "ad5e3f...",
  "refreshToken": "...",
  "expiresIn": 2592000
}

The token is good for 30 days. Store it securely.

Use the token

Every authenticated request sends the token in the Authorization header.

curl 'https://api-ha-prod-p8.handbid.dev/v3/bidder/my-auctions' \
  -H 'Authorization: Bearer ad5e3f...'

Full details — including the captcha-fallback path and the SMS-cost throttle that defends it — live on the Authentication page.

2. List the bidder’s auctions

curl 'https://api-ha-prod-p8.handbid.dev/v3/bidder/my-auctions?limit=10' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Iphone: 1'

{
  "auctions": [
    {
      "id": 45417,
      "guid": "c1b41927-689f-4c20-8621-534e05ffbacc",
      "name": "Annual Passholder Picks",
      "organizationName": "Magical Memories Foundation",
      "status": "open",
      "startTime": 1779510610,
      "endTime": 1779597010,
      "currency": "USD",
      "imageUrl": "https://cdn.hand.bid/.../image.jpg",
      "featuredItems": [ /* up to 4 */ ]
    }
  ],
  "totalCount": 7
}

The guid is the auction’s UUID. You’ll use it to join Socket.IO rooms for realtime updates — see Realtime.

3. Show the bell badge

The notifications endpoint has a count-only mode that’s safe to poll on app foreground.

curl 'https://api-ha-prod-p8.handbid.dev/v3/bidder/notifications?limit=0' \
  -H 'Authorization: Bearer <token>'

{
  "notifications": [],
  "totalCount": 24,
  "unreadCount": 7
}

The two integers are what you render. The empty array is a deliberate signal that you asked for a count, not a page — when the user actually opens the notifications screen, drop the limit=0 to get the rows.

4. Place a bid

curl -X POST 'https://api-ha-prod-p8.handbid.dev/v3/item/460314/bid' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 250 }'

A 200 means the bid landed. The response includes the new state — winning, outbid, etc. — and the current price after the bid was applied. Errors follow the standard error envelope.

5. Mark notifications read

When the user opens the notifications screen, fire a single bulk-read:

curl -X PUT 'https://api-ha-prod-p8.handbid.dev/v3/bidder/notifications/read-all' \
  -H 'Authorization: Bearer <token>'

{ "count": 7 }

Idempotent — calling it again returns { "count": 0 }. Run it before navigating to an item detail too, so badges stay accurate when the user taps without scrolling.

What’s next

Authentication — captcha gates, refresh tokens, the SMS-cost throttle
Errors — every error code and what to do when you see it
Rate limiting — per-endpoint budgets and the Retry-After contract
Realtime — Socket.IO rooms by auction GUID
API Reference — the rest of the surface