Introduction

Welcome to the Batchmates API documentation. Batchmates is a comprehensive platform that facilitates educational funding through campaigns, donations, and institutional partnerships in the Philippines.

Overview

The Batchmates API is built on REST principles, providing a predictable and intuitive interface. Our API supports various client types with consistent response formats and comprehensive error handling.

Base URL

https://batchmates-v2.revlv.com/api/v1

All API requests should be made to this base URL followed by the endpoint path.

Core Features

Campaign Management

Create and manage fundraising campaigns for scholarships and educational support. Campaigns can be general (institution-wide) or individual (specific student needs).

Donations & Subscriptions

Process one-time donations or set up recurring subscriptions with integrated payment gateways (Maya and Magpie). Support for multiple payment methods including GCash, PayMaya, and credit/debit cards.

Scholar Profiles

Manage beneficiary information with privacy-first design. Display scholar stories and backgrounds while protecting sensitive personal information.

Multi-Institution Support

Built for educational institutions with role-based access control. Supports system admins, institution admins, committee members, and donors.

Payment Integration

Seamless integration with Philippine payment gateways:

• Maya - GCash, PayMaya, cards
• Magpie - Multiple payment options

Real-time Updates

Webhook notifications for payment status, campaign updates, and donation confirmations.

Authentication

Batchmates supports two authentication methods to accommodate different client types:

See the Authentication Guide for implementation details.

Rate Limiting

API requests are rate-limited to ensure service stability and fair usage:

Rate limit information is provided in response headers. See Rate Limiting for handling strategies.

Response Format

Success Response

All successful API responses follow this structure:

{
  "success": true,
  "data": {
    // Response payload
  },
  "message": "Operation completed successfully"
}

Error Response

Error responses include detailed information for debugging:

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "amount": ["The amount must be at least 1."]
  }
}

See Error Handling for comprehensive error documentation.

Pagination

List endpoints return paginated results with metadata for navigation:

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      // Array of items
    ],
    "per_page": 15,
    "total": 150,
    "last_page": 10,
    "from": 1,
    "to": 15
  }
}

Pagination Parameters

Request Format

Query Parameters

Use query parameters for GET requests:

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

JSON Body

Use JSON for POST/PUT requests:

curl -X POST https://batchmates-v2.revlv.com/api/v1/donations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "campaign_id": 5,
    "amount": 1000,
    "payment_gateway": "maya"
  }'

Multipart Forms

Use multipart/form-data for file uploads:

curl -X PUT https://batchmates-v2.revlv.com/api/v1/profile \
  -H "Authorization: Bearer {token}" \
  -F "first_name=Juan" \
  -F "avatar=@profile.jpg"

Common HTTP Status Codes

API Endpoints Overview

Public Endpoints (No Authentication)

• Browse campaigns and institutions
• View scholars (privacy-filtered)
• Access FAQs and legal documents

Authenticated Endpoints

• Make donations
• Manage subscriptions
• Update profile
• View donation history
• Manage payment methods
• Receive notifications

Admin Endpoints

• Create campaigns
• Approve campaigns
• Manage institutions
• Process withdrawals
• View analytics

Getting Started

Popular Endpoints

SDKs and Libraries

Currently, the Batchmates API can be accessed using standard HTTP libraries in any programming language:

JavaScript/TypeScript

npm install axios
# or
npm install node-fetch

PHP

composer require guzzlehttp/guzzle

Python

pip install requests

Webhooks

Configure webhooks to receive real-time notifications for:

• Payment confirmations
• Recurring donation charges
• Campaign updates
• Subscription status changes

See Webhooks for setup instructions.

API Versioning

The current API version is v1. All endpoints are prefixed with /api/v1.

We follow semantic versioning and will maintain backward compatibility within major versions. Breaking changes will only be introduced in new major versions (v2, v3, etc.).

Version Header

API version is included in the base URL:

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

Best Practices

1. Always Use HTTPS

All API requests must use HTTPS for security.

2. Handle Errors Gracefully

Implement proper error handling for all status codes.

3. Respect Rate Limits

Monitor rate limit headers and implement backoff strategies.

4. Cache When Possible

Cache campaign listings, institution data, and FAQs to reduce API calls.

5. Use Webhooks

For payment status updates, use webhooks instead of polling.

6. Secure Your Tokens

Never expose API tokens in client-side code or public repositories.

Terms of Service

By using the Batchmates API, you agree to our Terms and Conditions and Privacy Policy.

Fair Use Policy

The API is provided for legitimate use in supporting educational fundraising. Abuse, scraping, or malicious use may result in access revocation.