​
Overview

The Volunteer API manages volunteer opportunities and tracks participation with GPS/QM verification. Activities can be verified at levels 30-100, with higher verification requiring location check-in and QR code scanning.

​
Endpoints

​
Create Opportunity

POST /api/volunteer/opportunities Create a new volunteer opportunity. Request Body: 
{
  "title": "Community Garden Cleanup",
  "description": "Help maintain the local community garden",
  "startDate": "2024-02-15T09:00:00Z",
  "endDate": "2024-02-15T12:00:00Z",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "123 Garden St, City, State"
  },
  "maxParticipants": 20,
  "skills": ["gardening", "outdoor_work", "team_leadership"]
}

​
List Opportunities

GET /api/volunteer/opportunities Retrieve volunteer opportunities with optional date filtering. Query Parameters:
  • startDate: Start date (ISO 8601)
  • endDate: End date (ISO 8601)
  • limit: Max results (default: 100)

​
Check In

POST /api/volunteer/check-in Check in to a volunteer activity with GPS verification. Request Body: 
{
  "opportunityId": "opportunity-uuid",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "accuracy": 10.5
  },
  "qrCode": "VOL20240215ABC123"
}
GPS Verification:
  • Location must be within 100 meters of opportunity location
  • Accuracy must be better than 50 meters
  • QR code optional but increases verification level

​
Check Out

POST /api/volunteer/check-out Check out from a volunteer activity. Request Body: 
{
  "activityId": "activity-uuid"
}
Automatic Calculations:
  • Hours volunteered calculated from check-in/check-out times
  • Verification level based on GPS accuracy and QR usage

​
Verification Levels

LevelRequirementsEvidence
30Basic check-in/outTime tracking only
50GPS verificationLocation within 100m
70QR code scanDigital check-in
90Photo evidenceActivity documentation
100Supervisor verificationManager confirmation

​
Skill Matching

Opportunities can specify required skills for better matching: 
{
  "skills": ["teaching", "mentoring", "event_planning"]
}
Users with matching skills are prioritized for opportunities.

​
Business Rules

  • GPS Required: Activities over level 30 require location verification
  • Time Tracking: Hours automatically calculated from check-in/check-out
  • Duplicate Prevention: Users cannot check in multiple times to same opportunity
  • Capacity Limits: Opportunities respect max participants setting
  • Caching: Opportunity lists cached for 5 minutes

​
Response Examples

Successful Check-in: 
{
  "data": {
    "id": "activity-uuid",
    "opportunityId": "opportunity-uuid",
    "userId": "user-uuid",
    "organizationId": "org-uuid",
    "checkInTime": "2024-02-15T09:15:00Z",
    "location": {
      "latitude": 40.7128,
      "longitude": -74.0060,
      "accuracy": 8.2
    },
    "verificationLevel": 70,
    "hours": null
  }
}
Check-out Response: 
{
  "data": {
    "id": "activity-uuid",
    "checkOutTime": "2024-02-15T12:30:00Z",
    "hours": 3.25,
    "verificationLevel": 70
  }
}