Batchmates

Campaigns

Browse active campaigns and view detailed information about fundraising efforts for scholarships and educational support.

The Campaign Model

Properties

  • Name
    id
    Type
    integer
    Description

    Unique identifier for the campaign

  • Name
    institution_id
    Type
    integer
    Description

    Foreign key to the institution

  • Name
    bank_account_id
    Type
    integer | null
    Description

    Foreign key to the committee bank account

  • Name
    created_by
    Type
    integer
    Description

    Foreign key to the user who created the campaign

  • Name
    title
    Type
    string
    Description

    Campaign title

  • Name
    description
    Type
    text
    Description

    Detailed campaign description

  • Name
    image
    Type
    string | null
    Description

    URL to campaign image

  • Name
    goal_amount
    Type
    decimal(12,2)
    Description

    Fundraising goal in PHP

  • Name
    raised_amount
    Type
    decimal(12,2)
    Description

    Amount raised so far

  • Name
    available_amount
    Type
    decimal(12,2)
    Description

    Amount available for withdrawal

  • Name
    contact_person_name
    Type
    string | null
    Description

    Contact person for campaign verification

  • Name
    contact_person_email
    Type
    string | null
    Description

    Contact person email

  • Name
    contact_person_phone
    Type
    string | null
    Description

    Contact person phone number

  • Name
    school_statement
    Type
    string | null
    Description

    Path to school endorsement letter file

  • Name
    campaign_type
    Type
    enum
    Description

    Type: general (institution/group cause) or individual (specific person need)

  • Name
    status
    Type
    enum
    Description

    Status: pending_review, active, completed, rejected, or closed

  • Name
    priority
    Type
    enum
    Description

    Priority level: normal or urgent

  • Name
    allow_recurring
    Type
    boolean
    Description

    Whether campaign accepts recurring donations

  • Name
    min_recurring_amount
    Type
    decimal(12,2) | null
    Description

    Minimum amount for recurring donations

  • Name
    suggested_amounts
    Type
    array | null
    Description

    Suggested donation amounts

  • Name
    end_date
    Type
    date | null
    Description

    Campaign end date

  • Name
    supporter_count
    Type
    integer
    Description

    Number of supporters

  • Name
    share_count
    Type
    integer
    Description

    Number of times shared

  • Name
    approved_by
    Type
    integer | null
    Description

    Foreign key to user who approved the campaign

  • Name
    approved_at
    Type
    timestamp | null
    Description

    When campaign was approved

  • Name
    created_at
    Type
    timestamp
    Description

    Record creation timestamp

  • Name
    updated_at
    Type
    timestamp
    Description

    Record last update timestamp

  • Name
    deleted_at
    Type
    timestamp | null
    Description

    Soft delete timestamp. Non-null only when fetching with ?trashed=1

Relationships

  • Name
    institution
    Type
    Institution
    Description

    The institution running the campaign

  • Name
    creator
    Type
    User
    Description

    The user who created the campaign

  • Name
    bankAccount
    Type
    CommitteeBankAccount | null
    Description

    Bank account for receiving funds

  • Name
    donations
    Type
    Donation[]
    Description

    All donations made to this campaign

  • Name
    scholars
    Type
    Scholar[]
    Description

    Scholars associated with this campaign

  • Name
    subscriptions
    Type
    DonationSubscription[]
    Description

    Recurring donation subscriptions

Computed Properties

  • Name
    days_left
    Type
    integer | null
    Description

    Days remaining until campaign ends (null if no end date)

  • Name
    progress_percentage
    Type
    float
    Description

    Percentage of goal reached (0-100)

  • Name
    monthly_recurring_amount
    Type
    decimal
    Description

    Total monthly recurring donation amount

  • Name
    active_subscribers_count
    Type
    integer
    Description

    Number of active recurring donors

GET/api/v1/campaigns

List Campaigns

Retrieves a paginated list of campaigns. Unauthenticated users see only active campaigns. Authenticated users see campaigns based on their role.

Authentication: Optional

Query Parameters

  • Name
    search
    Type
    string
    Description

    Search by title or description (case-insensitive)

  • Name
    status
    Type
    string
    Description

    Filter by status: active, completed, etc.

  • Name
    institution_id
    Type
    integer
    Description

    Filter by specific institution

  • Name
    campaign_type
    Type
    string
    Description

    Filter by type: general or individual

  • Name
    trashed
    Type
    integer
    Description

    Pass 1 to list soft-deleted campaigns instead. Only available to system_admin and institution_admin. Scoped to their institution automatically.

  • Name
    page
    Type
    integer
    Description

    Page number for pagination

Request

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

Response

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 5,
        "institution_id": 1,
        "title": "Engineering Scholarship Fund",
        "description": "Supporting bright engineering students...",
        "image": "campaigns/engineering-fund.jpg",
        "goal_amount": "100000.00",
        "raised_amount": "45000.00",
        "available_amount": "43500.00",
        "campaign_type": "general",
        "status": "active",
        "priority": "normal",
        "allow_recurring": true,
        "min_recurring_amount": "100.00",
        "end_date": "2024-12-31",
        "supporter_count": 125,
        "days_left": 85,
        "progress_percentage": 45.0,
        "created_at": "2024-01-15T10:00:00.000000Z",
        "institution": {
          "id": 1,
          "name": "University of the Philippines",
          "logo": "institutions/up.jpg"
        },
        "creator": {
          "id": 10,
          "name": "Juan Dela Cruz"
        },
        "scholars": [
          {
            "id": 3,
            "display_name": "Maria",
            "story": "Aspiring civil engineer from Tondo...",
            "gender": "female",
            "age": 19,
            "photo": "https://storage/.../maria.jpg"
          }
        ]
      }
    ],
    "per_page": 15,
    "total": 24,
    "last_page": 2
  }
}

Request (With Search)

curl -G https://batchmates-v2.revlv.com/api/v1/campaigns \
  -d "search=scholarship" \
  -d "campaign_type=individual"
GET/api/v1/campaigns/{id}

Get Campaign

Retrieves detailed information about a specific campaign, including scholars, donations, and institution details.

Authentication: Optional

Path Parameters

  • Name
    id
    Type
    integer
    Description

    The campaign ID

Request

curl https://batchmates-v2.revlv.com/api/v1/campaigns/5

Response

{
  "success": true,
  "data": {
    "id": 5,
    "institution_id": 1,
    "bank_account_id": 2,
    "created_by": 10,
    "title": "Engineering Scholarship Fund",
    "description": "Supporting bright engineering students who lack financial resources...",
    "image": "campaigns/engineering-fund.jpg",
    "goal_amount": "100000.00",
    "raised_amount": "45000.00",
    "available_amount": "43500.00",
    "contact_person_name": "Prof. Juan Santos",
    "contact_person_email": "jsantos@up.edu.ph",
    "contact_person_phone": "+639171234567",
    "school_statement": "documents/endorsement.pdf",
    "campaign_type": "general",
    "status": "active",
    "priority": "normal",
    "allow_recurring": true,
    "min_recurring_amount": "100.00",
    "suggested_amounts": [100, 500, 1000, 5000],
    "end_date": "2024-12-31",
    "supporter_count": 125,
    "share_count": 45,
    "approved_by": 1,
    "approved_at": "2024-01-20T14:00:00.000000Z",
    "days_left": 85,
    "progress_percentage": 45.0,
    "monthly_recurring_amount": "2500.00",
    "active_subscribers_count": 12,
    "created_at": "2024-01-15T10:00:00.000000Z",
    "updated_at": "2024-02-01T09:00:00.000000Z",
    "institution": {
      "id": 1,
      "name": "University of the Philippines",
      "slug": "university-of-the-philippines",
      "logo": "institutions/up.jpg",
      "city": "Quezon City"
    },
    "creator": {
      "id": 10,
      "name": "Juan Dela Cruz",
      "email": "juan@example.com"
    },
    "bankAccount": {
      "id": 2,
      "bank_name": "BPI",
      "account_number": "****5678",
      "account_name": "UP Engineering Alumni Committee"
    },
    "scholars": [
      {
        "id": 3,
        "display_name": "Maria",
        "story": "Aspiring civil engineer from Tondo, Manila. Dreams of building safer infrastructure for communities.",
        "gender": "female",
        "age": 19,
        "photo": "https://storage/.../maria.jpg"
      },
      {
        "id": 7,
        "display_name": "Pedro",
        "story": "First in family to attend university. Passionate about renewable energy.",
        "gender": "male",
        "age": 20,
        "photo": "https://storage/.../pedro.jpg"
      }
    ],
    "donations": [
      {
        "id": 45,
        "amount": "1000.00",
        "donor_display_name": "Anonymous Donor",
        "paid_at": "2024-02-05T10:00:00.000000Z"
      }
    ]
  },
  "related_campaigns": [
    {
      "id": 8,
      "institution_id": 1,
      "title": "Computer Science Scholarship",
      "image": "campaigns/cs-fund.jpg",
      "goal_amount": "80000.00",
      "raised_amount": "32000.00",
      "available_amount": "30000.00",
      "campaign_type": "general",
      "status": "active",
      "priority": "normal",
      "allow_recurring": true,
      "min_recurring_amount": "100.00",
      "suggested_amounts": [100, 500, 1000],
      "end_date": "2024-12-31",
      "days_left": 85,
      "progress_percentage": 40.0,
      "supporter_count": 67,
      "share_count": 12
    }
  ]
}

related_campaigns

Up to 4 active campaigns are returned alongside the main campaign. They are selected by matching either the same institution_id or the same campaign_type, ordered by supporter_count descending. Use this to render a "More campaigns like this" section.

Campaign Types

  • Name
    general
    Description

    Institution or group cause supporting multiple students or a general fund

  • Name
    individual
    Description

    Specific person's educational need or urgent situation

Both types can have scholars attached through the campaign-scholar relationship.

Campaign Status

  • Name
    pending_review
    Description

    Awaiting approval from institution committee

  • Name
    active
    Description

    Currently accepting donations

  • Name
    completed
    Description

    Goal reached or campaign ended successfully

  • Name
    rejected
    Description

    Not approved by committee

  • Name
    closed
    Description

    Manually closed by administrators

Note: Mobile users and guests see only active campaigns. The Total Goal stat only counts campaigns in active or completed status — pending_review campaigns are excluded until approved.

Campaign Deletion

Campaigns use soft deletes — deleted records are flagged with deleted_at and remain in the database. All related donation history is preserved.

Who can delete

RoleCan delete
system_adminAny pending_review or rejected campaign
institution_admin / creatorTheir own pending_review or rejected campaigns within their institution
AnyoneCannot delete active, completed, or closed campaigns

Active campaigns with real donation data cannot be deleted to prevent accidental data loss.

Viewing deleted campaigns

curl -G https://batchmates-v2.revlv.com/api/v1/campaigns \
  -d "trashed=1" \
  -H "Authorization: Bearer {token}"

Returns only soft-deleted campaigns. Requires system_admin or institution_admin role. Results are still scoped to the user's institution for institution admins.

Recurring Donations

Campaigns with allow_recurring: true accept subscription-based donations:

{
  "allow_recurring": true,
  "min_recurring_amount": "100.00",
  "monthly_recurring_amount": "2500.00",
  "active_subscribers_count": 12
}
  • min_recurring_amount: Minimum monthly subscription amount
  • monthly_recurring_amount: Total monthly recurring revenue
  • active_subscribers_count: Number of active recurring donors

See Subscriptions API for creating recurring donations.

Campaign Progress

Track campaign progress through computed properties:

{
  "goal_amount": "100000.00",
  "raised_amount": "45000.00",
  "progress_percentage": 45.0,
  "days_left": 85,
  "supporter_count": 125
}
  • progress_percentage: Capped at 100% even if over-funded
  • days_left: Calculated from end_date, returns 0 if expired
  • supporter_count: Number of unique donors

Scholars in Campaigns

Campaigns can feature one or more scholars:

{
  "scholars": [
    {
      "id": 3,
      "display_name": "Maria",
      "story": "Aspiring civil engineer...",
      "gender": "female",
      "age": 19,
      "photo": "https://..."
    }
  ]
}

Privacy Note: Scholar personal information is filtered to show only public-safe data (display name, story, age, gender, photo). Full details are not exposed to donors.

See Scholars API for more information.

Search & Filters

Search by Text

Searches campaign titles and descriptions:

curl -G https://batchmates-v2.revlv.com/api/v1/campaigns \
  -d "search=engineering%20scholarship"

Filter by Institution

View campaigns from a specific school:

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

Filter by Type

# General campaigns
curl -G https://batchmates-v2.revlv.com/api/v1/campaigns \
  -d "campaign_type=general"

# Individual campaigns
curl -G https://batchmates-v2.revlv.com/api/v1/campaigns \
  -d "campaign_type=individual"

Combine Filters

curl -G https://batchmates-v2.revlv.com/api/v1/campaigns \
  -d "institution_id=1" \
  -d "status=active" \
  -d "campaign_type=individual"

Making Donations

To donate to a campaign, use the campaign ID with the Donations API:

{
  "campaign_id": 5,
  "amount": 1000,
  "payment_gateway": "magpie"
}

For recurring donations, see Subscriptions API.

Error Responses

  • Name
    404 Not Found
    Description

    Campaign does not exist

Not Found Error

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

Was this page helpful?