POST /v3/auction/{auctionId}/guests/register — create-or-register a ticket buyer as a guest

POST

/v3/auction/{auctionId}/guests/register

const url = 'https://api-ha-prod-p8.handbid.dev/v3/auction/4821/guests/register';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"idempotencyKey":"squadup:order-8841:ticket-2","email":"guest@example.com","firstName":"Taylor","lastName":"Pearce","phone":"3055551234","phoneCountry":"US","registerBidder":true,"sendWelcome":true,"checkIn":false,"externalRef":{"provider":"squadup","orderId":"order-8841","ticketId":"ticket-2"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api-ha-prod-p8.handbid.dev/v3/auction/4821/guests/register \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "idempotencyKey": "squadup:order-8841:ticket-2", "email": "guest@example.com", "firstName": "Taylor", "lastName": "Pearce", "phone": "3055551234", "phoneCountry": "US", "registerBidder": true, "sendWelcome": true, "checkIn": false, "externalRef": { "provider": "squadup", "orderId": "order-8841", "ticketId": "ticket-2" } }'

Create-or-register a ticket buyer as an auction guest — the integration point for an external ticketing platform selling access to this auction. Available since Release 18.

Auth: raw organization API token only (Authorization: Bearer <org API token>), the same pattern used to generate auto-login links. A user OAuth2 bearer is refused 401 — this endpoint never accepts one. The token’s organization must have the contract entitlement allowPartnerRegistration; when it does not, a new idempotencyKey is rejected 403 (a replay of an already-known key is never blocked by this gate).

Deliberately 200, not 204: every response — first application or idempotent replay — returns a full body. The caller is a ticketing platform, not a signed-in Handbid user: it has no other way to learn the guid / aurId / paddleId this call just produced, and holds no key it could use to read them back afterward.

Idempotency contract — idempotencyKey is the dedupe key, scoped to your organization:

Same key + same email, registerBidder, sendWelcome, checkIn, and externalRef.ticketId (case-insensitive on email / ticketId) → replay. Returns the original outcome forever: outcome: "alreadyApplied" with originalOutcome set to what happened the first time (created or linked). This is the recommended integration pattern — retry with the same key on every uncertain response, not just on a network failure.
Same key + a different email, registerBidder, sendWelcome, checkIn, or externalRef.ticketId → 409 conflict. The key is already bound to a different request; mint a new idempotencyKey instead of reusing this one.
Same key + a different firstName, lastName, phone, phoneCountry, externalRef.provider, or externalRef.orderId → replay with the original values (first-write-wins). These fields sit outside the replay fingerprint, so a later value is silently ignored rather than overwriting the first registration.
A brand-new key against an archived auction → 404. A replay of a known key on an auction that has since archived → 200 with archived: true (nothing further can change).

Example of the alternate alreadyApplied shape returned on replay (200):

{
  "outcome": "alreadyApplied",
  "originalOutcome": "created",
  "guid": "b1f2b6b0-3e9e-4c9a-9d3f-8f2a1e9c7b10",
  "aurId": 48213,
  "userId": 90142,
  "paddleId": 101,
  "state": { "isBidder": 1, "isCheckedin": 0, "participationStatusId": 1, "isDeleted": 0 },
  "phone": { "accepted": true, "e164": "+13055551234", "reason": null },
  "welcome": "pending",
  "checkedInAt": null,
  "archived": false
}

Field reference:

Field	Required	Notes
`idempotencyKey`	Yes	1–64 characters, `[A-Za-z0-9:_-.]`. Scoped to your organization — see the idempotency contract above.
`email`	Yes	RFC 5322 address, at most 128 characters. Part of the replay fingerprint (case-insensitive).
`firstName`	Yes	1–64 characters, no control characters. First-write-wins on replay.
`lastName`	Yes	Same rules as `firstName`.
`phone`	No	At most 32 characters. First-write-wins on replay. Parsed against `phoneCountry`; see the Ticketing Partners guide’s phone-number rules.
`phoneCountry`	No	ISO 3166-1 alpha-2. Default `US`. First-write-wins on replay.
`registerBidder`	No	JSON boolean, default `true`. Part of the replay fingerprint.
`sendWelcome`	No	JSON boolean, default `true`. Part of the replay fingerprint.
`checkIn`	No	JSON boolean, default `false`. Part of the replay fingerprint.
`externalRef.provider`	No	At most 32 characters. First-write-wins on replay.
`externalRef.orderId`	No	At most 64 characters. First-write-wins on replay.
`externalRef.ticketId`	No	At most 64 characters. Part of the replay fingerprint (case-insensitive).

Errors: 400 validation_error (bad/unknown field), 401 unauthorized (missing/invalid org API token, or a user OAuth2 bearer), 403 forbidden (partner registration not enabled for this organization, the token’s organization does not own this auction, or the organization’s bidder limit is reached), 404 not_found (auction not found or archived, new key only), 409 conflict (idempotency-key reuse with different fingerprint fields, a concurrent request for the same key still in flight — retry after 2s, or the matched account is locked), 429 rate_limited (120 requests/min per organization token), 503 unavailable (transient — retry with the SAME idempotencyKey).

Authorizations

bearer

Parameters

Path Parameters

auctionId

required

integer

Example

Request Body^required

application/json

object

idempotencyKey

required

Dedupe key, scoped to your organization. Reuse it on every retry.

string

>= 1 characters <= 64 characters /^[A-Za-z0-9:_.-]{1,64}$/

email

required

RFC 5322 address. Part of the replay fingerprint.

string

<= 128 characters

firstName

required

string

>= 1 characters <= 64 characters

lastName

required

string

>= 1 characters <= 64 characters

phone

Optional. Parsed against phoneCountry.

string

<= 32 characters

phoneCountry

ISO 3166-1 alpha-2. Default US.

string

registerBidder

Default true. Part of the replay fingerprint.

boolean

sendWelcome

Default true. Part of the replay fingerprint.

boolean

checkIn

Default false. Part of the replay fingerprint.

boolean

externalRef

Optional. Free-form pointers back into the partner’s own system.

object

provider

string

<= 32 characters

orderId

string

<= 64 characters

ticketId

Part of the replay fingerprint (case-insensitive).

string

<= 64 characters

Example

{
  "idempotencyKey": "squadup:order-8841:ticket-2",
  "email": "guest@example.com",
  "firstName": "Taylor",
  "lastName": "Pearce",
  "phone": "3055551234",
  "phoneCountry": "US",
  "registerBidder": true,
  "sendWelcome": true,
  "checkIn": false,
  "externalRef": {
    "provider": "squadup",
    "orderId": "order-8841",
    "ticketId": "ticket-2"
  }
}

Responses

200

Applied (first time) or replayed (idempotent retry) — see the idempotency contract above. outcome is created (new bidder account), linked (existing user matched by email, newly registered as a guest of this auction), or alreadyApplied (idempotent replay; originalOutcome carries what happened the first time). archived reflects the auction’s current state.

application/json

Example

{
  "outcome": "created",
  "guid": "b1f2b6b0-3e9e-4c9a-9d3f-8f2a1e9c7b10",
  "aurId": 48213,
  "userId": 90142,
  "paddleId": 101,
  "state": {
    "isBidder": 1,
    "isCheckedin": 0,
    "participationStatusId": 1,
    "isDeleted": 0
  },
  "phone": {
    "accepted": true,
    "e164": "+13055551234",
    "reason": null
  },
  "welcome": "pending",
  "checkedInAt": null,
  "archived": false
}

400

Validation error — an unknown field, or a field that failed the checks in the field reference above.

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

{
  "error": "validation_error",
  "message": "`idempotencyKey` is required: 1–64 characters of [A-Za-z0-9:_-.]"
}

401

Missing or invalid organization API token, or a user OAuth2 bearer (never accepted here).

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

{
  "error": "unauthorized",
  "message": "organization API token required"
}

403

Partner registration is not enabled for this organization (contract entitlement allowPartnerRegistration is off, new keys only). Also returned when the token’s organization does not own this auction, or when the organization’s bidder limit has been reached.

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

{
  "error": "forbidden",
  "message": "partner registration is not enabled for this organization"
}

404

Auction not found or archived, and this idempotencyKey has never been used before.

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

{
  "error": "not_found",
  "message": "auction not found or archived"
}

409

idempotencyKey already used with a different email / registerBidder / sendWelcome / checkIn / externalRef.ticketId — mint a new key. Also returned (with retryAfter: 2) when a concurrent request for the same key is still being applied, or when the matched account is locked.

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

{
  "error": "conflict",
  "message": "idempotencyKey already used with a different request"
}

429

Rate limit exceeded — 120 requests/min per organization API token.

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

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 8 seconds.",
  "retryAfter": 8
}

POST /v3/auction/{auctionId}/guests/register — create-or-register a ticket buyer as a guest

Authorizations

Parameters

Path Parameters

Example

Request Body required

Example

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

409

Example

429

Example

Request Body^required