🎖️ Badge System API Documentation

Endpoints

1. List All Badges

GET /api/badges/

Returns all available badge definitions.

Response:

[
  {
    "id": 1,
    "badge_type": "NEIGHBORHOOD_HERO",
    "badge_type_display": "Neighborhood Hero",
    "name": "Neighborhood Hero",
    "description": "Volunteered for more than 10 different neighbors",
    "icon_url": "",
    "created_at": "2025-12-12T05:29:04.154432Z"
  }
]

---

2. Get Badge Types

GET /api/badges/types/

Returns all badge type enums with their labels.

Response:

[
  {
    "value": "NEIGHBORHOOD_HERO",
    "label": "Neighborhood Hero"
  },
  {
    "value": "JACK_OF_ALL_TRADES",
    "label": "Jack of All Trades"
  }
]

---

3. List User Badges

GET /api/user-badges/
GET /api/user-badges/?user_id=123

Returns earned badges. Optionally filter by user_id.

Response:

[
  {
    "id": 78,
    "user_id": 197,
    "username": "john_doe",
    "badge": {
      "id": 17,
      "badge_type": "PLATE_NOT_EMPTY",
      "badge_type_display": "Plate is Not Sent Back Empty",
      "name": "Plate is Not Sent Back Empty",
      "description": "Both created requests and volunteered to help others",
      "icon_url": "",
      "created_at": "2025-12-12T05:29:04.154432Z"
    },
    "earned_at": "2025-12-12T05:39:32.655857Z"
  }
]

---

4. Get My Badges

GET /api/user-badges/my_badges/

Auth Required: ✅
Returns authenticated user's badges in simplified format.

Response:

[
  {
    "badge_name": "Neighborhood Hero",
    "badge_type": "NEIGHBORHOOD_HERO",
    "badge_icon": "",
    "earned_at": "2025-12-12T05:39:32.655857Z"
  }
]

---

5. Manual Badge Check

POST /api/user-badges/check_all/

Auth Required: ✅
Manually triggers badge checking for authenticated user.

Response:

{
  "message": "Badge check completed. 2 new badges awarded.",
  "badges_awarded": ["NEIGHBORHOOD_HERO", "JACK_OF_ALL_TRADES"]
}

---

6. Admin: Check User Badges

POST /api/user-badges/check_user/

Auth Required: ✅ (Admin only)
Triggers badge checking for a specific user.

Request Body:

{
  "user_id": 123
}

Response:

{
  "message": "Badge check completed for john_doe. 1 new badges awarded.",
  "badges_awarded": ["RAPID_RESPONDER"]
}

---

User Profile Enhancement

The GET /api/users/{id}/ endpoint now includes badge information:

{
  "id": 1,
  "username": "john_doe",
  "badges": [
    {
      "badge_name": "Neighborhood Hero",
      "badge_type": "NEIGHBORHOOD_HERO",
      "badge_icon": "",
      "earned_at": "2025-12-12T05:39:32.655857Z"
    }
  ],
  "badges_count": 5
}

---

Badge Types Reference

Badge Type	Trigger
NEIGHBORHOOD_HERO	10+ different requesters helped
JACK_OF_ALL_TRADES	5+ different categories
SELECTED_VOLUNTEER	Chosen from multiple candidates
CARING_CONTRIBUTOR	10+ volunteer requests
HELP_AND_TRAVEL	2+ different cities
RAPID_RESPONDER	Volunteered within 15 minutes
THE_UNSUNG_HERO	Completed 3+ day old task
THE_LIFESAVER	Completed high urgency task
NIGHT_OWL	Volunteered at night (11 PM - 5 AM)
THE_HOLIDAY_HERO	Volunteered on national holiday
JUST_PERFECT	3 perfect reviews (5.0)
RISING_HELPER	5+ reviews, avg >= 4.0
GENTLE_COMMUNICATOR	5+ communication reviews >= 4.5
MODEL_CITIZEN	Safety rating >= 4.5
RELIABLE_NEIGHBOUR	Reliability rating > 4.5
PEOPLE_TRUST_YOU	10+ followers
PLATE_NOT_EMPTY	Both created and volunteered
FAR_SIGHTED	Created request 30+ days ahead
FULL_GALLERY	Used all 4 photos
THE_ICEBREAKER	First comment posted

---

Notes

• 🔄 Automatic Awarding: Badges are automatically checked and awarded via signals
• 🔒 Idempotent: Badges are never awarded twice
• 🌐 Public Access: Badge listing endpoints are public, no auth required
• 🔑 Auth Required: Only my_badges and check_all endpoints require authentication