The JustGive.online API allows you to programmatically interact with your donation platform. You can create and manage donations, donors, campaigns, and more.

All API requests are made to the base URL: https://api.justgive.online/v1

Request Format

The API accepts requests with JSON-encoded bodies. Always include the Content-Type: application/json header with your requests.

Response Format

All responses are returned in JSON format with appropriate HTTP status codes. Successful requests will return a 2xx status code, while errors will return a 4xx or 5xx status code.

To authenticate API requests, you'll need an API key that you can generate from the Admin Dashboard.

API Keys

Include your API key in the Authorization header of each request:

Authorization: Bearer YOUR_API_KEY

Authentication Example

fetch('https://api.justgive.online/v1/donations', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => console.log(data));

List Donations

Retrieve a list of donations with optional filtering.

Query Parameters

Parameter	Type	Description
limit	integer	Number of results to return (default: 10, max: 100)
offset	integer	Offset for pagination (default: 0)
campaign	string	Filter by campaign ID
donor	string	Filter by donor ID
status	string	Filter by status (completed, pending, failed)
date_from	string	Filter by date range (YYYY-MM-DD)
date_to	string	Filter by date range (YYYY-MM-DD)

Response Example

{
  "data": [
    {
      "id": "don_12345",
      "amount": 100.00,
      "currency": "USD",
      "status": "completed",
      "donor_id": "dnr_67890",
      "campaign_id": "cmp_54321",
      "created_at": "2023-06-15T10:30:00Z",
      "is_recurring": false
    },
    {
      "id": "don_12346",
      "amount": 50.00,
      "currency": "USD",
      "status": "completed",
      "donor_id": "dnr_67891",
      "campaign_id": "cmp_54321",
      "created_at": "2023-06-14T15:45:00Z",
      "is_recurring": true
    }
  ],
  "meta": {
    "total": 243,
    "limit": 10,
    "offset": 0
  }
}

Get Donation

Retrieve a specific donation by ID.

Response Example

{
  "id": "don_12345",
  "amount": 100.00,
  "currency": "USD",
  "status": "completed",
  "donor_id": "dnr_67890",
  "campaign_id": "cmp_54321",
  "created_at": "2023-06-15T10:30:00Z",
  "is_recurring": false,
  "receipt_url": "https://justgive.online/receipts/don_12345",
  "payment_method": {
    "type": "card",
    "last4": "4242",
    "brand": "visa"
  },
  "metadata": {
    "utm_source": "website",
    "utm_campaign": "summer"
  }
}

Create Donation

Create a new donation.

Request Body

{
  "amount": 100.00,
  "currency": "USD",
  "donor_id": "dnr_67890",
  "campaign_id": "cmp_54321",
  "is_recurring": false,
  "payment_token": "tok_visa",
  "metadata": {
    "utm_source": "website",
    "utm_campaign": "summer"
  }
}

List Donors

Retrieve a list of donors with optional filtering.

Response Example

{
  "data": [
    {
      "id": "dnr_67890",
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "total_donated": 750.00,
      "donation_count": 5,
      "created_at": "2023-01-15T10:30:00Z"
    },
    {
      "id": "dnr_67891",
      "email": "jane.smith@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "total_donated": 350.00,
      "donation_count": 3,
      "created_at": "2023-02-20T15:45:00Z"
    }
  ],
  "meta": {
    "total": 1482,
    "limit": 10,
    "offset": 0
  }
}

Get Donor

Retrieve a specific donor by ID.

Create Donor

Create a new donor.

Request Body

{
  "email": "new.donor@example.com",
  "first_name": "New",
  "last_name": "Donor",
  "phone": "+15551234567",
  "address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94107",
    "country": "US"
  }
}

List Campaigns

Retrieve a list of campaigns.

Get Campaign

Retrieve a specific campaign by ID.

Response Example

{
  "id": "cmp_54321",
  "name": "Education for All",
  "description": "Help us provide quality education to underprivileged communities.",
  "goal_amount": 50000.00,
  "current_amount": 25450.00,
  "currency": "USD",
  "start_date": "2023-05-01T00:00:00Z",
  "end_date": "2023-08-31T23:59:59Z",
  "status": "active",
  "donor_count": 243,
  "donation_count": 287
}

Donation Summary

Get a summary of donations for a specific time period.

Query Parameters

Parameter	Type	Description
start_date	string	Start date (YYYY-MM-DD)
end_date	string	End date (YYYY-MM-DD)
campaign_id	string	Optional campaign filter

Donor Retention

Get donor retention metrics.

Webhooks allow you to receive real-time notifications when events occur in your account.

Available Events

Event	Description
donation.created	A new donation is created
donation.completed	A donation payment is completed
donation.failed	A donation payment fails
donor.created	A new donor is created
campaign.goal_reached	A campaign reaches its fundraising goal

Create Webhook Endpoint

Register a URL to receive webhook events.

Request Body

{
  "url": "https://your-site.com/webhook/donation-events",
  "events": ["donation.created", "donation.completed"],
  "description": "Donation processing webhook"
}

Verifying Webhooks

To ensure webhooks are coming from JustGive.online, we sign each request with a secret key.

// Example webhook verification in Node.js
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(digest),
    Buffer.from(signature)
  );
}

The API uses standard HTTP status codes to indicate success or failure of requests.

Common Error Codes

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - You don't have permission
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end

Error Response Format

{
  "error": {
    "type": "invalid_request_error",
    "message": "The donation amount must be greater than zero.",
    "code": "invalid_amount",
    "param": "amount"
  }
}