Profile

registration)
1. User│ reaches│ profile└── stepfullName after(from completingGoogle/Apple phoneaccount) verification│ and│ preferences
└──
2. UserprofilePhotoUrl updates(from profilesocial account) │ │ └── email (from auth provider) │ │ │ │ 2. REGISTRATION (user choice) │ │ └── preferredLanguage │ │ └── theme │ │ │ │ 3. ONBOARDING (user completes) │ │ └── phoneNumber (verified via PUTOTP) /api/v1/profile│ with│ required└── fields
3. Backend auto-detects completion when fullName, username, and bio are all set
4. Onboarding status updated to COMPLETED automatically
5. User redirected to main app/dashboard

Profile Photo Flow

1. Upload photo via File Management APIpreferences (POSTfrom /api/v1/files/upload-singleonboarding withpages) directory│ │ │ │ 4. PROFILE)
2. AddCOMPLETION photo(final URLstep) to│ profile│ via└── POSTusername /api/v1/profile/photo
(required,
3. Setunique) primary│ photo│ via└── PATCHbio /api/v1/profile/photo/primary(required) │ │ └── fullName (can edit Firebase default) │ │ └── gender, link (optional)
4. Remove│ photo│ via│ DELETE│ /api/v1/profile/photoWhen user completes: fullName + username + bio │ │ └── Onboarding auto-completes if needed
at

Username│ Selection│ Flow

1. Check availability via GET /api/v1/profile/username/check?username=desired_name
2. If available: Proceed with profile update
3. If taken: Prompt user to choose different username

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-01-02T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-01-02T10:30:45",
  "data": "Error description"
}└─────────────────────────────────────────────────────────────────────────┘

Endpoints

1. Get Current Profile

Purpose: Retrieve the authenticatedcurrent user's complete profile information.

Endpoint: GET {base_url}/profile

Access Level: 🔒 Protected (Requires valid access token)

Authentication: Bearer Token

Request Headers:

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Profile retrieved successfully"retrieved",
  "action_time": "2025-01-02T10:05T10:30:45",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@gmail.user@example.com",
    "username": "johndoe",
    "phoneNumber": "+255712345678",
    "fullName": "John Doe",
    "bio": "Passionate softwareSoftware developer withpassionate 5+about years of experience in mobile and web development. Looking for exciting opportunities in East Africa's tech ecosystem."tech",
    "gender": "MALE",
    "link": "https://linkedin.com/in/johndoe"johndoe.com",
    "profilePhotoUrls": [
      "http:https://localhost:9000/fursa-550e8400.../files.fursahub.com/bucket/profile/a1b2c3d4_photo1.photo1.jpg",
      "http:https://localhost:9000/fursa-550e8400.../files.fursahub.com/bucket/profile/b2c3d4e5_photo2.photo2.jpg"
    ],
    "primaryPhotoUrl": "http:https://localhost:9000/fursa-550e8400.../files.fursahub.com/bucket/profile/a1b2c3d4_photo1.photo1.jpg",
    "isPhoneVerified": true,
    "isEmailVerified": true,
    "preferredLanguage": "en"sw",
    "theme": "DARK",
    "authProvider": "GOOGLE",
    "role": "ROLE_USER",
    "onboardingStatus": "COMPLETED",
    "isOnboardingComplete": true,
    "createdAt": "2025-01-01T08:00:00",
    "updatedAt": "2025-01-02T10:05T10:30:45"00"
  }
}

Success Response Fields:

Error Response JSON Sample:

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token is missing or invalid",
  "action_time": "2025-01-02T10:30:45",
  "data": "Token is missing or invalid"
}

2. Update Profile

Purpose: Update user profile fields.information. AutomaticallyOnly completes onboarding when requiredprovided fields (fullName, username, bio) are all set.updated.

Endpoint: PUT {base_url}/profile

Access Level: 🔒 Protected (Requires valid access token)

Authentication: Bearer Token

Request Headers:

Request JSON Sample:

{
  "fullName": "John Doe"Doe Updated",
  "username": "johndoe"johndoe_new",
  "bio": "PassionateBuilding softwarethe developer with 5+ yearsfuture of experienceopportunity in mobileEast and web development."Africa",
  "gender": "MALE",
  "link": "https://linkedin.com/in/johndoe",
  "profilePhotoUrls": [
    "https://files.fursahub.com/bucket/profile/new-photo.jpg"
  ],
  "theme": "LIGHT",
  "preferredLanguage": "en"
}

Request Body Parameters:

*Required for onboarding completion

Auto-Completion Logic: When the following conditions are met, onboarding automatically completes:

• fullName is not null/empty
• username is not null/empty
• bio is not null/empty
• Current onboardingStatus is PENDING_PROFILE_COMPLETION

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Profile updated successfully"updated",
  "action_time": "2025-01-02T10:30:45"05T10:35:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@gmail.user@example.com",
    "username": "johndoe",
    "phoneNumber": "+255712345678"johndoe_new",
    "fullName": "John Doe"Doe Updated",
    "bio": "PassionateBuilding softwarethe developer with 5+ yearsfuture of experienceopportunity in mobileEast and web development."Africa",
    "gender"theme": "MALE"LIGHT",
    "link": "https://linkedin.com/in/johndoe",
    "profilePhotoUrls": [],
    "primaryPhotoUrl": null,
    "isPhoneVerified": true,
    "isEmailVerified": true,
    "preferredLanguage": "en",
    "authProvider": "GOOGLE",
    "role": "ROLE_USER",
    "onboardingStatus": "COMPLETED",
    "isOnboardingComplete": true,
    "createdAt": "2025-01-01T08:00:00",
    "updatedAt": "2025-01-02T10:30:45"true
  }
}

Success Response Fields:

Error Response JSON SamplesResponses:

Username Already Taken (409):

{
  "success": false,
  "httpStatus": "CONFLICT",
  "message": "Username already taken",
  "action_time": "2025-01-02T10:30:45"05T10:35:00",
  "data": "Username 'johndoe' is already intaken"
use"}

Invalid Language Code (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid or inactive language code: xx",
  "action_time": "2025-01-05T10:35:00",
  "data": "Invalid or inactive language code: xx"
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-01-02T10:30:45"05T10:35:00",
  "data": {
    "username": "Username can only contain letters, numbers, and underscores",
    "fullName": "Name must be 3-30 characters, alphanumeric and underscores only",
    "bio": "Bio must not exceed 5002-100 characters",
    "link": "Must be a valid URL"
  }
}

Invalid

{
  "theme": "DARK"
}

{
  "success": false,true,
  "httpStatus": "BAD_REQUEST"OK",
  "message": "InvalidTheme gender value"updated",
  "action_time": "2025-01-02T10:30:45"05T10:40:00",
  "data": {
    "Invalidtheme": gender:"DARK"
  UNKNOWN. Valid values: MALE, FEMALE, OTHER, PREFER_NOT_TO_SAY"}
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "Username is available",
  "action_time": "2025-01-02T10:30:45"05T10:45:00",
  "data": {
    "username": "johndoe_new"newusername",
    "available": true
  }
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "Username is not available"taken",
  "action_time": "2025-01-02T10:30:45"05T10:45:00",
  "data": {
    "username": "johndoe"existinguser",
    "available": false
  }
}

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid username format",
  "action_time": "2025-01-02T10:30:45",
  "data": "Username must be 3-30 characters, containing only letters, numbers, and underscores"
}

{
  "photoUrl": "http:https://localhost:9000/fursa-550e8400.../files.fursahub.com/bucket/profile/a1b2c3d4_photo.new-photo.jpg"
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "Photo added successfully",
  "action_time": "2025-01-02T10:30:45",
  "data": {
    "profilePhotoUrls": [
      "http://localhost:9000/fursa-550e8400.../profile/a1b2c3d4_photo.jpg"
    ],
    "primaryPhotoUrl": "http://localhost:9000/fursa-550e8400.../profile/a1b2c3d4_photo.jpg",
    "totalPhotos": 1
  }
}

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid photo URL",
  "action_time": "2025-01-02T10:30:45",
  "data": "Photo URL must be a valid URL"
}

{
  "success": false,
  "httpStatus": "CONFLICT",
  "message": "Photo already exists",
  "action_time": "2025-01-02T10:30:45",
  "data": "This photo URL is already in your profile"
}

{
  "photoUrl": "http://localhost:9000/fursa-550e8400.../profile/a1b2c3d4_photo.jpg"
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "Photo removed successfully"added",
  "action_time": "2025-01-02T10:30:45"05T10:50:00",
  "data": {
    "profilePhotoUrls": [
      "http:https://localhost:9000/fursa-550e8400...files.fursahub.com/bucket/profile/photo1.jpg",
      "https://files.fursahub.com/bucket/profile/b2c3d4e5_photo2.new-photo.jpg"
    ],
    "primaryPhotoUrl": "http:https://localhost:9000/fursa-550e8400.../files.fursahub.com/bucket/profile/b2c3d4e5_photo2.jpg",
    "totalPhotos": 1,
    "removedUrl": "http://localhost:9000/fursa-550e8400.../profile/a1b2c3d4_photo.photo1.jpg"
  }
}

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Photo not found",
  "action_time": "2025-01-02T10:30:45",
  "data": "This photo URL is not in your profile"
}

{
  "photoUrl": "http://localhost:9000/fursa-550e8400.../profile/b2c3d4e5_photo2.jpg"
}

{
  "success": true,
  "httpStatus": "OK",
  "message": "PrimaryPhoto photo updated"removed",
  "action_time": "2025-01-02T10:30:45"05T10:55:00",
  "data": {
    "primaryPhotoUrl": "http://localhost:9000/fursa-550e8400.../profile/b2c3d4e5_photo2.jpg",
    "profilePhotoUrls": [
      "http:https://localhost:9000/fursa-550e8400.../files.fursahub.com/bucket/profile/a1b2c3d4_photo1.photo1.jpg"
    ],
    "http://localhost:9000/fursa-550e8400.../profile/b2c3d4e5_photo2.jpg"
    ]
  }
}

{
  "success": false,
  "httpStatus"primaryPhotoUrl": "BAD_REQUEST",https://files.fursahub.com/bucket/profile/photo1.jpg"
  "message": "Photo not in profile",
  "action_time": "2025-01-02T10:30:45",
  "data": "Cannot set primary: This photo URL is not in your profile photo list"}
}

fullName != null AND
username != null AND
bio != null ANDWhen onboardingStatus = "PENDING_PROFILE_COMPLETION":

1. GET /profile to fetch current data
2. Show form with:
   ├── fullName (pre-filled from Firebase)
   ├── username (auto-generated, editable)
   │   └── On change: GET /profile/username/check
   ├── bio (required)
   ├── gender (optional)
   └── link (optional)
3. PUT /profile with form data
4. If isOnboardingComplete = PENDING_PROFILE_COMPLETIONtrue → Navigate to home

Theme Toggle:
└── PATCH /profile/theme with selected theme
└── Apply theme immediately on client

Language Change:
└── PUT /profile with preferredLanguage
└── Reload UI with new language strings

Profile Edit:
└── PUT /profile with changed fields only

Adding Photo:
1. Upload via Files API (POST /files/upload-single)
2. Get permanentUrl from response
3. POST /profile/photo with photoUrl

Removing Photo:
1. DELETE /profile/photo?photoUrl=...
2. Optionally delete from Files API