​
Overview

The Kindness API enables organizations to track and verify acts of kindness, peer recognition, and community service. Each act can be verified at different levels and includes optional media attachments.

​
Endpoints

​
Create Kindness Act

POST /api/kindness Record a new kindness act with verification level and optional media. Request Body: 
{
  "description": "Helped a colleague debug their code",
  "category": "peer_recognition",
  "verificationLevel": 2,
  "recipientId": "user-uuid",
  "media": [
    {
      "type": "image",
      "url": "https://storage.example.com/photo.jpg"
    }
  ]
}
Response: 
{
  "data": {
    "id": "kindness-uuid",
    "description": "Helped a colleague debug their code",
    "category": "peer_recognition",
    "verificationLevel": 2,
    "recipientId": "user-uuid",
    "userId": "sender-uuid",
    "organizationId": "org-uuid",
    "media": [
      {
        "type": "image",
        "url": "https://storage.example.com/photo.jpg"
      }
    ],
    "createdAt": "2024-01-15T14:30:00Z"
  }
}

​
List Kindness Acts

GET /api/kindness Retrieve kindness acts with optional filtering. Query Parameters:
  • category: Filter by category
  • userId: Filter by specific user
  • startDate: Start date (ISO 8601)
  • endDate: End date (ISO 8601)
  • limit: Max results (default: 100, max: 1000)

​
Get Statistics

GET /api/kindness/stats Retrieve aggregated kindness statistics for analytics. Response: 
{
  "data": {
    "total": 245,
    "byCategory": {
      "peer_recognition": 156,
      "community": 67,
      "wellbeing": 22
    },
    "averageRippleScore": 3.8,
    "totalRippleScore": 931,
    "recentCount": 34,
    "topRecipients": [
      {
        "userId": "user-uuid-1",
        "count": 18
      }
    ]
  }
}

​
Verification Levels

LevelDescriptionEvidence Required
1Self-reportedNone
2Peer acknowledgmentRecipient confirmation
3Supervisor verificationManager approval
4HR documentationFormal recognition
5External validationThird-party verification

​
Categories

  • peer_recognition: Recognition between colleagues
  • community: Community service or volunteering
  • wellbeing: Mental health or wellness support

​
Business Rules

  • All acts are automatically scoped to the user’s organization
  • Media attachments are optional but recommended for higher verification levels
  • Statistics are cached for 5 minutes for performance
  • Recipients can be other employees or external individuals