POST /v3/user/addresses — create

POST

/v3/user/addresses

const url = 'https://api-ha-prod-p8.handbid.dev/v3/user/addresses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': '*/*'},
  body: '"{\n  \"addressType\": \"Home\",\n  \"street1\": \"1313 Disneyland Dr\",\n  \"street2\": \"\",\n  \"city\": \"Anaheim\",\n  \"province\": \"CA\",\n  \"postalCode\": \"92802\",\n  \"country\": \"US\",\n  \"isPrimary\": true\n}"'
};

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/user/addresses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: */*' \
  --data '"{\n  \"addressType\": \"Home\",\n  \"street1\": \"1313 Disneyland Dr\",\n  \"street2\": \"\",\n  \"city\": \"Anaheim\",\n  \"province\": \"CA\",\n  \"postalCode\": \"92802\",\n  \"country\": \"US\",\n  \"isPrimary\": true\n}"'

NEW (HAN-2041, 2026-06-05). Create an address for the authenticated user. Auth required; the owner is always the bearer-token user (no client bidderId).

Body:

Field	Required	Notes
`addressType`	Yes	Type name (e.g. `Home`, `Work`). Unknown name → `400`.
`street1`	—	Also accepts `userAddressStreet1` / `address1`.
`street2`	—	Also accepts `userAddressStreet2` / `address2`.
`city`	—	Also accepts `userAddressCity` / `locality`.
`province`	—	Region name; resolved to `provinceId` using the country. Or pass `provinceId` directly.
`postalCode`	—	Also accepts `postal_code` / `zip`.
`country`	—	ISO code or name (`countryCode` / `country`); resolved to `countryId`. Or pass `countryId`.
`googlePlacesId`	—	Also accepts `googlePlaceId`.
`isPrimary`	—	`true` makes this the primary (shipping) address and demotes the prior primary.

Response (204 No Content): empty body. Re-read via GET /v3/user/addresses.

Errors: 400 validation_error (missing/unknown addressType, or per-field address errors returned under fields), 401 anonymous.

Side-effects: when isPrimary=true, the write-bridge syncs the flattened address into the legacy users.shippingAddress scalar (the value surfaced by GET /v3/user/profile). Drops the address-list cache and broadcasts an async event.address ({action:"add"}) to room:{usersGuid}.

Rate limit: userAddressWrite.

Authorizations

bearer

Request Body

*/*

string

Example

"{\n  \"addressType\": \"Home\",\n  \"street1\": \"1313 Disneyland Dr\",\n  \"street2\": \"\",\n  \"city\": \"Anaheim\",\n  \"province\": \"CA\",\n  \"postalCode\": \"92802\",\n  \"country\": \"US\",\n  \"isPrimary\": true\n}"

Responses

200

Successful response

application/json