Scholars

Browse and view information about scholars supported through campaigns. Scholar information is privacy-filtered to protect personal details.

The Scholar Model

Properties

Relationships

Public View Properties

For donors and guests, scholars are returned in a privacy-filtered format:

List Scholars

curl -G https://batchmates-v2.revlv.com/api/v1/scholars \
  -d "institution_id=1" \
  -d "per_page=20"

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 3,
        "display_name": "Maria",
        "story": "Aspiring civil engineer from Tondo, Manila. Dreams of building safer infrastructure for underserved communities.",
        "gender": "female",
        "age": 19,
        "photo": "https://storage.batchmates-v2.revlv.com/scholars/maria.jpg"
      },
      {
        "id": 7,
        "display_name": "Pedro",
        "story": "First in his family to attend university. Passionate about renewable energy and sustainable development.",
        "gender": "male",
        "age": 20,
        "photo": "https://storage.batchmates-v2.revlv.com/scholars/pedro.jpg"
      }
    ],
    "per_page": 20,
    "total": 45,
    "last_page": 3
  }
}

curl -G https://batchmates-v2.revlv.com/api/v1/scholars \
  -d "search=maria" \
  -d "gender=female"

Get Scholar

curl https://batchmates-v2.revlv.com/api/v1/scholars/3

{
  "id": 3,
  "display_name": "Maria",
  "story": "Aspiring civil engineer from Tondo, Manila. Despite financial hardships, Maria maintained top grades throughout high school. She dreams of building safer infrastructure for underserved communities in the Philippines.",
  "gender": "female",
  "age": 19,
  "photo": "https://storage.batchmates-v2.revlv.com/scholars/maria.jpg",
  "campaigns": [
    {
      "id": 5,
      "title": "Engineering Scholarship Fund",
      "status": "active",
      "institution": {
        "id": 1,
        "name": "University of the Philippines"
      }
    }
  ]
}

{
  "message": "No query results for model [Scholar] 999"
}

Privacy & Data Protection

What Donors See (Public View)

For privacy and security, donors and guests see only:

• Display name (nickname or first name)
• Background story
• Age (calculated from birthdate)
• Gender
• Photo
• Associated campaigns

What's Protected (Admin-Only)

The following information is hidden from public view:

• Full name (first, middle, last)
• Exact birthdate
• Contact information (email, phone, address)
• Specific location details
• Civil status and religion
• Family background details

Why? This protects scholars from unwanted contact, identity theft, and maintains their privacy while still allowing donors to connect with their stories.

Scholar Display Names

Scholars are shown using their preferred display name:

displayName = scholar.nickname || scholar.first_name

Examples:

• If nickname is "Maria" → shows "Maria"
• If no nickname, first_name is "Pedro" → shows "Pedro"

This provides a personal touch while protecting full identity.

Age Calculation

Age is dynamically calculated from birthdate:

{
  "birthdate": "2005-03-15",
  "age": 19
}

If birthdate is not set, age returns null.

Search & Filters

Search by Name

Searches first name, last name, and nickname:

curl -G https://batchmates-v2.revlv.com/api/v1/scholars \
  -d "search=maria"

Filter by Institution

View scholars from a specific school:

curl -G https://batchmates-v2.revlv.com/api/v1/scholars \
  -d "institution_id=1"

Filter by Gender

curl -G https://batchmates-v2.revlv.com/api/v1/scholars \
  -d "gender=female"

Combine Filters

curl -G https://batchmates-v2.revlv.com/api/v1/scholars \
  -d "institution_id=1" \
  -d "gender=male" \
  -d "per_page=10"

Scholars in Campaigns

Scholars are linked to campaigns through the campaign_scholar pivot table. One scholar can be supported by multiple campaigns:

{
  "id": 3,
  "display_name": "Maria",
  "campaigns": [
    {
      "id": 5,
      "title": "Engineering Scholarship Fund",
      "status": "active"
    },
    {
      "id": 12,
      "title": "Women in STEM Initiative",
      "status": "active"
    }
  ]
}

When viewing a campaign, you'll see its associated scholars. When viewing a scholar, you'll see their campaigns.

Supporting Scholars

To support a scholar, donate to one of their associated campaigns:

1. View scholar details to see their campaigns array
2. Choose a campaign from the list
3. Use the campaign ID with the Donations API

{
  "campaign_id": 5,
  "amount": 1000,
  "payment_gateway": "maya",
  "message": "Supporting Maria's engineering dreams!"
}

Scholar Stories

Each scholar can share their background story:

{
  "story": "Aspiring civil engineer from Tondo, Manila. Despite financial hardships, Maria maintained top grades throughout high school. She dreams of building safer infrastructure for underserved communities in the Philippines."
}

Stories help donors connect with scholars on a personal level while maintaining appropriate privacy boundaries.

Error Responses

{
  "message": "No query results for model [Scholar] 999"
}