Auth, account and addresses

3. Auth & account

Source: routes/v1/customer_route.js → customer_controller.js

3.1 POST /api/v1/mobile/register — create customer

Auth: Brand · Handler: createCustomer

Body payload (at least one of email / phoneNumber required):

field	type	req	notes
email	string(email)	one-of	lowercased; + not allowed
phoneNumber	string	one-of	non-digits stripped, min 8
phone_prefix	string	✅ if phoneNumber	e.g. +1
password	string	—	min 8
firstName, lastName, fullName	string	—
dateOfBirth	ISO date	—
tags	string	—
source	enum	—	customer_source_types, default organic
user_profile, user_description, username, gender	string	—

Query: medium (enum), device (enum) — both optional.

3.2 POST /api/v1/mobile/login — login

Auth: Brand · Handler: loginUser

Body payload — needs one identifier and one credential:

field	type	req	notes
email	string(email)	one-of email/phoneNumber
phoneNumber	string	one-of
phone_prefix	string	✅ if phoneNumber
otp	string	one-of otp/password
password	string	one-of	min 8
source	enum	—	customer_source_types
recaptcha_token	string	✅ if the brand has recaptcha_required	otherwise optional

Query: referralCode, medium, device — all optional. Returns the customer JWT.

3.3 POST /api/v1/mobile/send-otp — send login OTP

Auth: Brand · Handler: sendOTP

Body payload: email or phoneNumber (+ phone_prefix), recaptcha_token (required if brand demands it). Query: hubId (number), source, medium, device.

3.4 POST /api/v1/mobile/register/google-oauth

Auth: Brand · Handler: registerGoogleVerifiedCustomer

Body payload: email ✅, oauth_access_token ✅, plus optional firstName, lastName, fullName, dateOfBirth (ISO), oauth_json (object), user_profile, user_description. Query: referralCode, source, medium, device.

3.5 POST /api/v1/mobile/register/apple-oauth

Auth: Brand · Handler: registerAppleVerifiedCustomer

Body payload: oauth_access_token ✅ (only field accepted). Query: referralCode, source, medium, device.

3.6 POST /api/v1/mobile/resetPassword — send reset OTP

Auth: Brand · Handler: sendResetPasswordOTP

Body payload: exactly one of email / phoneNumber (xor), phone_prefix required with phoneNumber.

3.7 POST /api/v1/mobile/resetPassword/confirm

Auth: Brand · Handler: sendResetPasswordConfirmation

Body payload: otp ✅, and exactly one of email / phoneNumber (+ optional phone_prefix).

3.8 POST /api/v1/mobile/changePassword/:passwordToken

Auth: Brand · Handler: changePassword

Path: passwordToken ✅. Body payload: password ✅ (min 8).

3.9 GET /api/v1/mobile/user-detail — current customer

Auth: Customer · Handler: getCustomerDetails · Query: hubId (number, optional; token value wins if present).

3.10 PUT /api/v1/mobile/details/update

Auth: Customer · Handler: updateDetails

Body payload — all optional, send only what changes:

field	type	notes
firstName, lastName, fullName	string
email	string(email)	+ not allowed
password	string	min 8
dateOfBirth	ISO date
phoneNumber	string	requires phone_prefix
phone_prefix	string
tags, user_profile, user_description, username, gender	string
open_to_trade	boolean	exposes the user in trade listings
show_collections_for_trade	boolean
geocode	string	must match /^[A-Z]{1,4} [A-Z0-9][A-Z0-9 -]{1,9}, [A-Z]{2}$/

3.11 GET /api/v1/user/mobile/available/username

Auth: Customer · Handler: check_username_availability · Query: username ✅.

3.12 Account merge (3 calls, in order)

Auth: Customer on all three.

Step	Endpoint	Handler	Body payload
1	POST /api/v1/mobile/user/merge-user/send-otp	sendOtpForUserMergeOperation	email or phoneNumber (+phone_prefix)
2	POST /api/v1/mobile/user/merge-user/validate-otp	validateOTPForUserMergeOperation	same + otp (optional in schema, required in practice)
3	POST /api/v1/mobile/user/merge-user	mergeDuplicateUsers	email or phoneNumber (+phone_prefix), plus optional firstName, lastName, username, dateOfBirth, gender, user_profile, user_description

3.13 Deactivation / deregistration

Auth: Customer on all.

Endpoint	Handler	Body
POST /api/v1/mobile/user/deactivate/direct	deactivateUserDirectly	none — deletes immediately
POST /api/v1/mobile/user/deactivate	deactivateUser	none — sends confirmation OTP
GET /api/v1/user/mobile/deregister/oauth	deactivateUser	none — same handler, OAuth-flow alias
POST /api/v1/mobile/user/deactivate/confirm	deactivateUserConfirmation	payload.otp ✅
PUT /api/v1/user/mobile/deregister/apple-oauth/confirm	deactivateUserConfirmation	payload.otp ✅ — same handler, Apple alias

3.14 GET /api/v1/user/brand/mobile/customers — brand customer directory

Auth: Customer · Handler: getAllBrandCustomers Query: search (string), limit + offset — the pair is only applied when both are sent.

3.15 GET /api/v1/mobile/user-point/leaderboard (guest) · GET /api/v1/user/mobile/user-point/leaderboard (customer)

Handler: getUserPointLeaderboards (one handler, two mounts). No params. The customer variant additionally marks the caller's own row.

3.16 POST /api/v1/user/mobile/verify/image/license

Auth: Customer · Handler: verifyUserImageWithLicense Body payload: target_image ✅ (string/URL), source_image ✅ (string/URL). AWS Rekognition face-match against the stored licence.

---

4. Addresses

Source: routes/v1/address_route.js → address_controller.js · Auth: Customer on all.

4.1 POST /api/v1/user/mobile/address/add

Handler: addUserAddress · Body payload:

field	type	req	notes
address1	string	✅
city, state, zip	string	✅
country	string	✅	ISO code, must be in country_iso_codes
addressString	string	✅	full formatted address
address2, county, short_state, what3words, name	string	—
deliveryCharges	number	—
isPrimary	boolean	—	default true
type	string	—	default shipping (addressTypes)
latLng	{ lat: number ✅, lng: number ✅ }	—

4.2 GET /api/v1/user/mobile/address — list

Handler: getUserAddress · No params.

4.3 PUT /api/v1/user/mobile/address/update/:addressId

Handler: updateUserAddress · Path: addressId (number) ✅. Body payload: same fields as 4.1 but all optional (payload object itself is required, what3words/isPrimary included, no isPrimary default).

4.4 DELETE /api/v1/user/mobile/address/delete/:addressId

Handler: deleteAddressById · Path: addressId (number) ✅.

Related pages

• Mobile API overview
• Authentication mechanics
• Product authentication
• Enum reference
• Duplicates, aliases and quirks
• Customer management
• Login flow
• Signup flow
• Forgot password flow
• Threads — where the feed service reads customer rows from