Auth guards vary by endpoint — JWT users can only access their own record. Admin key has full access.

Overview

User rows are created by the Auth module on first POST /auth/token. This module owns everything after creation: profile reads and writes, the onboarding transition, and soft-deletion. Phone number and user ID are immutable once set.

Onboarding Flow

New users start with status = ONBOARDING. Calling POST /users/{user_id}/add_details transitions them to ACTIVE and returns a fresh JWT. Every add_details field is optional and is merged over what POST /auth/token already stored. Onboarding completes once first_name, gender and dob are all present; until then the call returns 400 naming the missing fields and writes nothing, so the client can re-submit. last_name, email, occupation, id_proof, address and bank_details (ifsc_code + account_number) are optional — bank_details also creates the user’s SAVINGS account. Salutation is deduced from gender, never sent. Completing onboarding also creates the system-managed SELF dependant.
PATCH /users/{user_id} is not part of the onboarding path — an app user can only PATCH once they are ACTIVE. While ONBOARDING, profile fields are submitted through add_details.

Auth Guards by Endpoint

GET /users/{user_id} currently has no owner assertion at the handler or core layer — any authenticated caller who knows a user_id can read that profile. Treat ownership scoping as enforced only on the write and onboarding paths.

Searching & Filtering Users

GET /users accepts optional, AND-combined query parameters. All three search filters are case-insensitive prefix matches (starts-with), not substring.
Prefix means ?name=ravi matches “Ravi” and “Ravikumar” but not “Shravi”. Search terms are sanitized to alphanumerics + spaces, and must contain at least 3 alphanumeric characters — shorter or symbol-only terms (e.g. a blank ?name=) are ignored, not treated as match-everything.

Basic details for a platform’s users

GET /users/details/basic is the GET /users search above (same parameters, minus phone, platform_id — the platform comes from the token — and statuses — DEACTIVATED users are always left out) over one platform’s users, returning only user_id, first_name, last_name, occupation, gender and status. A contributor uses it to find a user, then opens their goals. The token decides what the caller can see; its values replace any x-platform-id or user_id that names something else: A user appears for a platform only while their platform_users row there is ACTIVE.
Contributor — search the platform's users by name
Response 200

Endpoints

GET /users

Admin only. Paginated list of users. Filter by statuses, creation time_range, and search by name / phone / user_id.

GET /users/details/basic

Search users with basic details only, scoped by the caller’s token.

GET /users/{user_id}

Fetch a user profile. JWT users can only fetch their own record.

PATCH /users/{user_id}

Partial profile update. Send only changed fields (first_name, last_name, email, occupation, id_proof, dob, gender, address). App user must be ACTIVE.id_proof is write-only — it is accepted here but never returned in any response. Supplying it sets or replaces the stored one.occupation is one of DRIVER, HOUSEKEEPING_STAFF or SECURITY; any other value is a 400. Omitting a field leaves it untouched — as with every other profile field, there is no way to clear one back to null once set.

POST /users/{user_id}/add_details

Merge the remaining profile fields and transition status → ACTIVE once first_name, gender and dob are present. Returns fresh JWT.

DELETE /users/{user_id}

Admin only. Soft-delete a user (status → DEACTIVATED).

Request / Response Examples


Error Codes