Fundraisers API

Manage fundraising campaigns with full CRUD operations and advanced filtering.

List Fundraisers

GET /api/v1/fundraisers

Retrieve a paginated list of active public fundraisers with optional filtering.

Query Parameters

• status (string) - Filter by status (e.g., active, draft)
• category (uuid) - Filter by category ID
• limit (integer) - Number of results (max 100, default 20)
• offset (integer) - Pagination offset (default 0)

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(`${API_BASE}/fundraisers?status=active&limit=20`);
const fundraisers = await response.json();

// Response format
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Help Local Food Bank",
    "slug": "help-local-food-bank",
    "summary": "Supporting families in need",
    "goal": 50000,
    "raised": 12500,
    "donor_count": 23,
    "status": "active",
    "owner": {
      "name": "John Doe",
      "avatar": "https://example.com/avatar.jpg"
    },
    "category": {
      "name": "Community",
      "emoji": "🏘️"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
]

Get Single Fundraiser

GET /api/v1/fundraisers/:slug

Retrieve detailed information about a specific fundraiser by slug or ID.

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const slug = 'help-local-food-bank';

const response = await fetch(`${API_BASE}/fundraisers/${slug}`);

if (!response.ok) {
  if (response.status === 404) {
    console.error('Fundraiser not found');
  }
  throw new Error('Failed to fetch fundraiser');
}

const fundraiser = await response.json();

// Response includes full details and statistics
console.log('Goal:', fundraiser.goal);
console.log('Raised:', fundraiser.raised);
console.log('Donors:', fundraiser.donor_count);
console.log('Days left:', fundraiser.days_left);

Create Fundraiser

POST /api/v1/fundraisers 🔒 Requires Authentication

Create a new fundraising campaign.

Request Body

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(`${API_BASE}/fundraisers`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  credentials: 'include',
  body: JSON.stringify({
    title: 'Help Support Local Food Bank',
    description: 'Raising funds to support families in need',
    goal: 50000,
    category_id: 'category-uuid-here',
    cover_image: 'https://example.com/image.jpg',
    location: 'Austin, TX',
    tags: ['community', 'food', 'families'],
    end_date: '2024-12-31'
  })
});

if (!response.ok) {
  const error = await response.json();
  console.error('Error:', error.message);
  throw new Error('Failed to create fundraiser');
}

const fundraiser = await response.json();
console.log('Created:', fundraiser);
// Fundraiser starts in 'draft' status by default

Update Fundraiser

PATCH /api/v1/fundraisers/:id 🔒 Requires Authentication

Update fundraiser details. Only the owner can update their fundraiser.

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const fundraiserId = '123e4567-e89b-12d3-a456-426614174000';

const response = await fetch(`${API_BASE}/fundraisers/${fundraiserId}`, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json'
  },
  credentials: 'include',
  body: JSON.stringify({
    title: 'Updated: Help Support Local Food Bank',
    description: 'Updated description with more details',
    goal: 75000,  // Increased goal
    status: 'active'  // Publish the campaign
  })
});

if (!response.ok) {
  if (response.status === 403) {
    console.error('Permission denied - not the owner');
  } else if (response.status === 404) {
    console.error('Fundraiser not found');
  }
  throw new Error('Failed to update fundraiser');
}

const updated = await response.json();
console.log('Updated:', updated);

Delete Fundraiser

DELETE /api/v1/fundraisers/:id 🔒 Requires Authentication

Delete a fundraiser. Only the owner can delete their fundraiser. Fundraisers with existing donations typically cannot be deleted, only archived.

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const fundraiserId = '123e4567-e89b-12d3-a456-426614174000';

const response = await fetch(`${API_BASE}/fundraisers/${fundraiserId}`, {
  method: 'DELETE',
  credentials: 'include'
});

if (!response.ok) {
  const error = await response.json();
  console.error('Error:', error.message);
  throw new Error('Failed to delete fundraiser');
}

console.log('Fundraiser deleted successfully');

Common Use Cases

Search Fundraisers

Search across titles and descriptions using the search query parameter:

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const searchTerm = 'medical emergency';

const response = await fetch(
  `${API_BASE}/fundraisers?search=${encodeURIComponent(searchTerm)}&status=active&limit=20`
);

const results = await response.json();
console.log(`Found ${results.length} fundraisers`);

Filter by Category

Get fundraisers in a specific category:

const API_BASE = 'https://api.fundlyhub.org/api/v1';
const categoryId = 'medical-category-uuid';

const response = await fetch(
  `${API_BASE}/fundraisers?category=${categoryId}&status=active`
);

const medicalFundraisers = await response.json();

Get User's Fundraisers

List all fundraisers created by the authenticated user:

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(`${API_BASE}/fundraisers/me`, {
  credentials: 'include'
});

const myFundraisers = await response.json();
console.log('My campaigns:', myFundraisers);

Filter by Location and Goal

Advanced filtering with multiple criteria:

const API_BASE = 'https://api.fundlyhub.org/api/v1';

// Find fundraisers in Texas with goals between $10,000-$100,000
const params = new URLSearchParams({
  location: 'TX',
  min_goal: '10000',
  max_goal: '100000',
  status: 'active'
});

const response = await fetch(`${API_BASE}/fundraisers?${params}`);
const fundraisers = await response.json();

Get Trending Fundraisers

Retrieve fundraisers with the most recent activity:

const API_BASE = 'https://api.fundlyhub.org/api/v1';

const response = await fetch(
  `${API_BASE}/fundraisers?sort=trending&limit=10`
);

const trending = await response.json();
trending.forEach(f => {
  console.log(`${f.title}: $${f.raised} raised`);
});

Response Codes

• 200 - Success
• 201 - Created successfully
• 400 - Bad request / Validation errors
• 401 - Authentication required
• 403 - Permission denied (not the owner)
• 404 - Fundraiser not found
• 429 - Rate limit exceeded
• 500 - Server error