Guide
Users
Once a user is signed in (see Authentication), these endpoints manage their profile, contact details, linked sign-in methods, and account lifecycle. A separate set of staff-only endpoints lets Admin and Support accounts look up, moderate, and manage other users. Every endpoint mentioned on this page lives under https://api.swiftgoma.com/api/v1/users.
Self-service vs. staff-only
Every endpoint on this page falls into one of two buckets:
| Bucket | Acts on | Requires |
|---|---|---|
| Self-service | The signed-in user's own account | Any valid session |
| Admin | A target user, by userId, given in the path | ADMIN or SUPPORT role — some actions ADMIN only |
Roles
Every account has exactly one role, which governs both what that account can do across the whole API and, here, who can act on other users.
| Role | Who |
|---|---|
| BUYER | Default role — shops and orders on the platform. |
| SELLER | Runs a shop, once seller onboarding and KYC are complete. |
| RIDER | Delivers orders. |
| SUPPORT | Staff — can moderate users but not delete accounts or change roles. |
| ADMIN | Staff — full access, including account deletion and role changes. |
Profile
A user's display name, preferred currency, and profile picture are the only self-describing fields they control directly.
| Field | Endpoint |
|---|---|
| Name / preferred currency | PATCH /profile |
| Profile picture | POST /profile/avatar |
Contact methods
Phone number and a secondary email both follow the same shape: request a code, then verify it. That two-step pattern shows up everywhere in this API — get comfortable with it once and it applies broadly.
Phone number
- 1
Adding a first number
POST /phone/request sends an SMS code, then POST /phone/verify confirms it. - 2
Changing an existing number
Same pattern, different endpoints: POST /phone/update/request sends the code to the new number, POST /phone/update/verify confirms and switches over.
Secondary email
- 1
Add and verify
POST /email/secondary/request emails a code to the new address, POST /email/secondary/verify confirms it. - 2
Remove it
DELETE /email/secondary — no code required, since it's just removing a contact point, not adding one.
Linked sign-in methods
A Google account can be linked to or unlinked from an existing SwiftGoma account at any time via POST /google/link and POST /google/unlink.
Don't lock the user out
Account deletion and recovery
- 1
Delete
POST /delete doesn't erase the account immediately. It's marked deleted, every session is revoked, and a grace period starts. - 2
Recover, within the grace period
POST /recovery/request sends a code by email, and POST /recovery/verify restores the account and signs the user back in — both endpoints are unauthenticated, since by definition the user has no valid session at this point.
Admin operations
Staff-only endpoints for looking up and moderating any user on the platform. Every one of these takes the target userId in the path.
| Action | Endpoint | Role |
|---|---|---|
| List / search users | GET / | ADMIN, SUPPORT |
| Get one user's detail | GET /:id | ADMIN, SUPPORT |
| Block / unblock | POST /:id/block · unblock | ADMIN, SUPPORT |
| Force logout | POST /:id/force-logout | ADMIN, SUPPORT |
| Manually verify email / phone | POST /:id/verify-email · verify-phone | ADMIN, SUPPORT |
| Delete / restore | POST /:id/delete · restore | ADMIN only |
| Change role | POST /:id/role | ADMIN only |
Why the ADMIN / SUPPORT split?