Quick Start

Get up and running with the FundlyHub API in under 5 minutes.

1. Base URL

All API requests go to:

https://api.fundlyhub.org/api/v1

For testing, use the staging environment:

https://api.staging.fundlyhub.org/api/v1

2. Your First Request

Fetch active fundraisers — no authentication required:

const response = await fetch('https://api.fundlyhub.org/api/v1/fundraisers?status=active&limit=5');
const fundraisers = await response.json();

fundraisers.forEach(f => {
  console.log(`${f.title}: $${f.raised} raised of $${f.goal}`);
});

# Using cURL
curl "https://api.fundlyhub.org/api/v1/fundraisers?status=active&limit=5" | jq .

3. Authentication

FundlyHub uses AWS Cognito with httpOnly cookie-based sessions. After signing in, include credentials: 'include' in all requests — no manual token handling needed.

Sign Up

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

// 1. Create account
await fetch(`${API_BASE}/cognito/signup`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecureP@ssw0rd!',
    name: 'John Doe'
  })
});

// 2. Confirm with email verification code
await fetch(`${API_BASE}/cognito/confirm`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    email: 'user@example.com',
    code: '123456'  // Code from email
  })
});

Sign In

const response = await fetch(`${API_BASE}/cognito/signin`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'SecureP@ssw0rd!'
  })
});

const { user } = await response.json();
console.log('Signed in as:', user.name);
// Session cookies are set automatically

Google SSO

Redirect the user to the Google SSO endpoint for one-click sign-in:

// Redirect to Google SSO
window.location.href = `${API_BASE}/cognito/oauth/google`;

TIP

See the full Authentication Guide for all endpoints including password reset, session refresh, and security features.

4. Make Authenticated Requests

With session cookies set, add credentials: 'include' to access protected endpoints:

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

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

// Create a new fundraiser
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'
  })
});

const fundraiser = await response.json();
console.log('Created:', fundraiser.title);

5. Handle Errors

The API returns standard HTTP status codes with structured error responses:

const response = await fetch(`${API_BASE}/fundraisers`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ title: '' })  // Missing required fields
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${response.status}: ${error.message}`);
  // Error 400: Title is required
}

Next Steps

• Authentication — Full auth flow, Google SSO, and security features
• Fundraisers API — Create, update, and manage campaigns
• Donations API — Process donations and receipts
• JavaScript Examples — Complete integration examples
• Rate Limits — Usage tiers and best practices