API
Welcome to the GiveWheel API. This API enables charities, companies, and individuals to integrate with the GiveWheel platform for fundraising, donations, events, and more.
Access your personal fundraising data, manage your donations, and update your profile.
Login with your username and password to obtain a token:
POST /api/auth/login/
Content-Type: application/json
{
"username": "[email protected]",
"password": "yourpassword"
}
Use the returned token in the Authorization header for subsequent requests:
Authorization: Bearer <your_token>GET /api/me/fundraisings/ - List your fundraising pagesGET /api/me/info/ - Get your user profileGET /api/me/fundraisings/
Authorization: Bearer <your_token>
GET /api/me/info/
Authorization: Bearer <your_token>
Access donation data, manage fundraising events, and integrate with GiveWheel for reporting and CRM. Use your API token for authentication.
A GiveWheel API key is required to access platform data. Request one here.
Include your API token in the Authorization header:
Authorization: Bearer <your_api_token>You must also include your Client ID in the header:
Client-ID: 1234Replace 1234 with your assigned 4-digit Client ID.
The charity_id in the URLs should correspond to your official Charity Commission ID.
GET /api/organisation/<charity_id>/fundraisings/ - List all fundraising events for your charityGET /api/organisation/<charity_id>/donations/fundraising/ - List all fundraising donations for your charityGET /api/organisation/<charity_id>/donations/other/ - List all single and allocation item donations for your charityGET /api/organisation/12345/fundraisings/
Authorization: Bearer <your_api_token>
Create and manage fundraising events, retrieve ticket sales, and participant data.
A GiveWheel API key is required. Request one here.
Include your token and Client ID on all requests:
Authorization: Bearer <your_api_token>
Client-ID: 1234Replace 1234 with your assigned 4-digit Client ID.
Retrieve all fundraising pages linked to your company. Includes an aggregate metrics object alongside paginated results.
GET /api/company/<company_id>/fundraisings/
Authorization: Bearer <your_api_token>
Client-ID: 1234Optional query param: ?time_since=2025-01-01
Response shape:
{
"metrics": {
"comp_single_count": 4,
"comp_series_count": 2,
"comp_series_fundraisercount": 48,
"employee_fundraising_count": 12,
"comp_raised": 18450.00,
"emp_raised": 3200.00
},
"count": 66,
"next": "/api/company/7/fundraisings/?limit=20&offset=20",
"previous": null,
"results": [ ... ]
}Look up a fundraising page by its full URL or shortlink. Useful when you have a URL from a QR code, email, or external system. No authentication required.
GET /api/fundraisings/url/?url=<url>Accepts both URL formats:
# Shortlink format
GET /api/fundraisings/url/?url=https://gvwhl.com/VKT0F
# Full page URL format
GET /api/fundraisings/url/?url=https://givewheel.com/fundraising/1234/janes-marathon-runReturns 404 if no matching page is found.
Retrieve a specific fundraising page by its numeric ID. Only accessible by the page owner.
GET /api/fundraisings/<id>/
Authorization: Bearer <your_api_token>Access ticket configuration, purchase records, and full registration data for ticketed events. All endpoints require the event owner.
Retrieve the configured ticket types (name, price, availability) for a ticketed event. Only accessible by the event owner.
GET /api/event/<event_id>/tickets/
Authorization: Bearer <your_api_token>Retrieve all individual ticket purchases for an event, including buyer details and check-in status. Only accessible by the event owner.
GET /api/event/<event_id>/ticket-purchases/
Authorization: Bearer <your_api_token>Retrieve complete registration records including answers to custom form questions. Responses are nested by purchase-level (e.g. dietary requirements) and ticket-level (e.g. t-shirt size). Only the event owner can access.
GET /api/event/<event_id>/registration-data/
Authorization: Bearer <your_api_token>Optional query param: ?updated_since=2025-06-01T00:00:00 — filters to records updated on or after this datetime.
Response example:
[
{
"id": 42,
"order_id": "ORD-00042",
"event_order_number": 3,
"registration_name": "Jane Doe",
"registration_email": "[email protected]",
"registration_address": "12 High Street",
"registration_postcode": "SW1A 1AA",
"amount": 50.00,
"status": "Completed",
"transaction_date": "2026-03-01T10:30:00Z",
"last_updated": "2026-03-01T10:31:00Z",
"number_tickets_purchased": 2,
"tickets_used": "1 / 2 tickets",
"mandatory_data_completed": true,
"discount_applied": ["EARLYBIRD"],
"order_data": [
{
"question": "Dietary requirements",
"response": "Vegan",
"apply_to": "Purchase"
}
],
"tickets": [
{
"ticket_id": "TKT-001",
"ticket_number": 1,
"ticket_type": "Standard Entry",
"ticket_price": 25.00,
"registration_attended": false,
"discount_code": "EARLYBIRD",
"responses": [
{ "question": "T-shirt size", "response": "M", "apply_to": "Ticket" }
]
}
]
}
]write permissions. Read-only tokens will receive a 403. Include your token and Client ID on all requests:
Authorization: Bearer <your_api_token>
Client-ID: 1234
Content-Type: application/jsonIf your token is linked to a company or charity organisation, the created page will be automatically linked to that entity.
| Scenario | Endpoint |
|---|---|
| Join a campaign / mass participation series | POST /api/fundraisings/create/<event_id>/ |
| Create a standalone fundraising page | POST /api/fundraisings/create/ |
When an event_id is provided, the page is created as a sub-page in that series. Title, content, dates, and event type are inherited automatically from the parent. The parent must already exist as a series event on GiveWheel.
Endpoint: POST /api/fundraisings/create/<event_id>/
title - set to "First Last's parent title"content - copied from parentevent_date, event_start_date - copied from parentNot inherited automatically: Charity allocation must be supplied explicitly - use charity_ids: ["Inherit"] to copy the parent's allocation.
| Field | Type | Required? | Notes |
|---|---|---|---|
email |
string | Required | Creates a GiveWheel account if not already registered. Matched case-insensitively. |
first_name |
string | Required | Applied to a new account; added to existing account if blank. |
last_name |
string | Required | Applied to a new account; added to existing account if blank. |
charity_ids |
array of strings | Required | Accepts Charity Commission IDs. Provide explicit IDs. IDs that don't exist on GiveWheel will return a 400 error. See the verify endpoint for a pre-flight bulk check. Where charities are set at the parent event level (NOT applicable for most events, pass ["Inherit"] to copy the parent event's charity allocation exactly. |
target |
integer | Optional | Fundraising target. Defaults to no target if omitted. |
display_name |
string | Optional | Name shown on the page. Defaults to "First Name, Last Name". |
event_close_date |
date (YYYY-MM-DD) | Optional | When the page closes for donations. Defaults to match parent event if omitted. |
override_duplicate |
boolean | Optional | Pass true to bypass the duplicate page check. Default: false. |
With explicit charity, custom target, and display name:
POST /api/fundraisings/create/456/
Authorization: Bearer <your_api_token>
Client-ID: 1234
Content-Type: application/json
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"charity_ids": ["1234567"],
"target": 500,
"display_name": "Jane's London Marathon"
}Providing charity_ids sets the charities for the fundraising page. Note, where multiple charities are specified, each charity will receive an equal share of the donations.
Inherit allocation from parent:
POST /api/fundraisings/create/456/
Authorization: Bearer <your_api_token>
Client-ID: 1234
Content-Type: application/json
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"charity_ids": ["Inherit"]
}Copies all Charity allocation records from the parent exactly, preserving percentshare values.
Without an event_id, the page is created as an independent fundraising page, not linked to any series. Title, content, and event date must be provided explicitly.
Endpoint: POST /api/fundraisings/create/
| Field | Type | Required? | Notes |
|---|---|---|---|
email |
string | Required | Creates a GiveWheel account if not already registered. Matched case-insensitively. |
first_name |
string | Required | Applied to a new account; added to existing account if blank. |
last_name |
string | Required | Applied to a new account; added to existing account if blank. |
title |
string | Required | The page title. |
content |
string | Required | Page description / body text. |
event_date |
date (YYYY-MM-DD) | Required | Main event / fundraising date. |
charity_ids |
array of strings | Required unless donorled_type="Unlimited"> |
Accepts Charity Commission IDs. Provide explicit IDs. IDs that don't exist on GiveWheel will return a 400 error. See the verify endpoint for a pre-flight bulk check. Note: Where creating a DonorLed page, behaviour depends on donorled_type - see DonorLed section. |
target |
integer | Optional | Fundraising target. Defaults to no target if omitted. |
hero_pic_url |
string (URL) | Optional | URL of a publicly accessible image to use as the page hero image. The image is downloaded, center-cropped to 16:9, resized to max 1920×1080, and compressed as JPEG. Must be publicly reachable and under 15 MB. Returns 400 if the URL is unreachable, not an image, or too large. |
display_name |
string | Optional | Name shown on the page. Defaults to "First Name, Last Name". |
event_start_date |
date (YYYY-MM-DD) | Optional | Used for pages with a date range. Date must be before the event_date. |
event_close_date |
date (YYYY-MM-DD) | Optional | When the page closes for donations. Defaults to event_date + 90 days if omitted. |
donorled_type |
string | Optional | "Unlimited", "Selective", or "Split". See DonorLed section below. |
POST /api/fundraisings/create/
Authorization: Bearer <your_api_token>
Client-ID: 1234
Content-Type: application/json
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"title": "Jane's Marathon Run",
"content": "I'm running 26.2 miles to raise money for a great cause!",
"event_date": "2026-10-04",
"event_close_date": "2026-10-11",
"charity_ids": ["1234567"],
"target": 1000
}event_close_date defaults to event_date + 90 days if omitted.
Note, where multiple charities are specified, each charity will receive an equal share of the donations.
DonorLed pages allow donors to choose which charity their donation goes to, rather than a fixed allocation. The donorled_type field controls the behaviour and determines how charity_ids is used.
donorled_type: "Unlimited"Donors can search and choose any charity on the platform. charity_ids is not required or used.
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"title": "Jane's Charity Run",
"content": "Donate and choose your own charity!",
"event_date": "2026-10-04",
"donorled_type": "Unlimited"
}donorled_type: "Selective"Donors choose from a pre-defined shortlist. charity_ids is required.
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"title": "Jane's Charity Run",
"content": "Choose from our three partner charities.",
"event_date": "2026-10-04",
"donorled_type": "Selective",
"charity_ids": ["1234567", "7654321", "9876543"]
}donorled_type: "Split" - or omit donorled_typeDonations are split equally between the specified charities and the donor's choice - 50% to each
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"title": "Jane's Charity Run",
"content": "Supporting two charities equally.",
"event_date": "2026-10-04",
"charity_ids": ["1234567", "7654321"]
}2 charities → 50% / 50%. 3 charities → 33.33% / 33.33% / 33.34%.
The API guards against accidental duplicates. If a page already exists for the same email address in the same series (or with the same title and event date for standalone pages), it returns 409 Conflict:
{
"error": "A fundraising page already exists for this user in this series.",
"hint": "To create a second page anyway, resubmit with \"override_duplicate\": true"
}To bypass, add "override_duplicate": true to your request body. Useful when the same participant legitimately needs two pages (e.g. two different events run by the same person).
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"charity_ids": ["1234567"],
"override_duplicate": true
}| Status | Meaning |
|---|---|
201 Created |
Page created. Returns the full fundraising page object. |
400 Bad Request |
Missing required fields, invalid email, unrecognised charity_id, event is not a series, or hero_pic_url could not be downloaded or processed. |
403 Forbidden |
Missing, expired, or read-only API token. |
404 Not Found |
The specified event_id does not exist. |
409 Conflict |
Duplicate page detected. Add "override_duplicate": true to proceed. |
POST /api/organisations/verify/
Before a bulk import, use this endpoint to check a list of charity IDs in one call.
For each ID it checks whether the charity is available for fundraising on GiveWheel.
Any IDs not found in either are returned in not_found — those will cause a 400 if passed to the create endpoint.
Requires the same write API token as the create endpoint. Maximum 100 IDs per request.
POST /api/organisations/verify/
Authorization: Bearer <your_api_token>
Content-Type: application/json
{
"charity_ids": ["1234567", "9876543", "0000000"]
}
// Response 200:
{
"found": ["1234567", "9876543"],
"not_found": ["0000000"]
}IDs in found are safe to use in the create endpoint. IDs in not_found are not recognised by GiveWheel or the Charity Commission and will need to be added manually.
Integrate GiveWheel data into your own platform, automate workflows, and access public fundraising data.
A GiveWheel API key is required to access platform data. Request one here.
Include your API token in the Authorization header:
Authorization: Bearer <your_api_token>You must also include your Client ID in the header:
Client-ID: 1234Replace 1234 with your assigned 4-digit Client ID.
The charity_id in the URLs should correspond to your official Charity Commission ID.
GET /api/organisation/<charity_id>/fundraisings/ - List all fundraising events for a charityGET /api/organisation/<charity_id>/donations/fundraising/ - List all fundraising donations for a charityGET /api/organisation/<charity_id>/donations/other/ - List all single and allocation item donations for a charityGET /api/organisation/12345/fundraisings/
Authorization: Bearer <your_api_token>
Retrieve all fundraising pages linked to your company. Includes an aggregate metrics object alongside paginated results.
GET /api/company/<company_id>/fundraisings/
Authorization: Bearer <your_api_token>
Client-ID: 1234Optional query param: ?time_since=2025-01-01
Response shape:
{
"metrics": {
"comp_single_count": 4,
"comp_series_count": 2,
"comp_series_fundraisercount": 48,
"employee_fundraising_count": 12,
"comp_raised": 18450.00,
"emp_raised": 3200.00
},
"count": 66,
"next": "/api/company/7/fundraisings/?limit=20&offset=20",
"previous": null,
"results": [ ... ]
}Look up a fundraising page by its full URL or shortlink. Useful when you have a URL from a QR code, email, or external system. No authentication required.
GET /api/fundraisings/url/?url=<url>Accepts both URL formats:
# Shortlink format
GET /api/fundraisings/url/?url=https://gvwhl.com/VKT0F
# Full page URL format
GET /api/fundraisings/url/?url=https://givewheel.com/fundraising/1234/janes-marathon-runReturns 404 if no matching page is found.
Retrieve a specific fundraising page by its numeric ID. Only accessible by the page owner.
GET /api/fundraisings/<id>/
Authorization: Bearer <your_api_token>Access ticket configuration, purchase records, and full registration data for ticketed events. All endpoints require the event owner.
Retrieve the configured ticket types (name, price, availability) for a ticketed event. Only accessible by the event owner.
GET /api/event/<event_id>/tickets/
Authorization: Bearer <your_api_token>Retrieve all individual ticket purchases for an event, including buyer details and check-in status. Only accessible by the event owner.
GET /api/event/<event_id>/ticket-purchases/
Authorization: Bearer <your_api_token>Retrieve complete registration records including answers to custom form questions. Responses are nested by purchase-level (e.g. dietary requirements) and ticket-level (e.g. t-shirt size). Only the event owner can access.
GET /api/event/<event_id>/registration-data/
Authorization: Bearer <your_api_token>Optional query param: ?updated_since=2025-06-01T00:00:00 — filters to records updated on or after this datetime.
Response example:
[
{
"id": 42,
"order_id": "ORD-00042",
"event_order_number": 3,
"registration_name": "Jane Doe",
"registration_email": "[email protected]",
"registration_address": "12 High Street",
"registration_postcode": "SW1A 1AA",
"amount": 50.00,
"status": "Completed",
"transaction_date": "2026-03-01T10:30:00Z",
"last_updated": "2026-03-01T10:31:00Z",
"number_tickets_purchased": 2,
"tickets_used": "1 / 2 tickets",
"mandatory_data_completed": true,
"discount_applied": ["EARLYBIRD"],
"order_data": [
{
"question": "Dietary requirements",
"response": "Vegan",
"apply_to": "Purchase"
}
],
"tickets": [
{
"ticket_id": "TKT-001",
"ticket_number": 1,
"ticket_type": "Standard Entry",
"ticket_price": 25.00,
"registration_attended": false,
"discount_code": "EARLYBIRD",
"responses": [
{ "question": "T-shirt size", "response": "M", "apply_to": "Ticket" }
]
}
]
}
]write permissions. Read-only tokens will receive a 403. Include your token and Client ID on all requests:
Authorization: Bearer <your_api_token>
Client-ID: 1234
Content-Type: application/jsonIf your token is linked to a company or charity organisation, the created page will be automatically linked to that entity.
| Scenario | Endpoint |
|---|---|
| Join a campaign / mass participation series | POST /api/fundraisings/create/<event_id>/ |
| Create a standalone fundraising page | POST /api/fundraisings/create/ |
When an event_id is provided, the page is created as a sub-page in that series. Title, content, dates, and event type are inherited automatically from the parent. The parent must already exist as a series event on GiveWheel.
Endpoint: POST /api/fundraisings/create/<event_id>/
title - set to "First Last's parent title"content - copied from parentevent_date, event_start_date - copied from parentNot inherited automatically: Charity allocation must be supplied explicitly - use charity_ids: ["Inherit"] to copy the parent's allocation.
| Field | Type | Required? | Notes |
|---|---|---|---|
email |
string | Required | Creates a GiveWheel account if not already registered. Matched case-insensitively. |
first_name |
string | Required | Applied to a new account; added to existing account if blank. |
last_name |
string | Required | Applied to a new account; added to existing account if blank. |
charity_ids |
array of strings | Required | Accepts Charity Commission IDs. Provide explicit IDs. IDs that don't exist on GiveWheel will return a 400 error. See the verify endpoint for a pre-flight bulk check. Where charities are set at the parent event level (NOT applicable for most events, pass ["Inherit"] to copy the parent event's charity allocation exactly. |
target |
integer | Optional | Fundraising target. Defaults to no target if omitted. |
display_name |
string | Optional | Name shown on the page. Defaults to "First Name, Last Name". |
event_close_date |
date (YYYY-MM-DD) | Optional | When the page closes for donations. Defaults to match parent event if omitted. |
override_duplicate |
boolean | Optional | Pass true to bypass the duplicate page check. Default: false. |
With explicit charity, custom target, and display name:
POST /api/fundraisings/create/456/
Authorization: Bearer <your_api_token>
Client-ID: 1234
Content-Type: application/json
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"charity_ids": ["1234567"],
"target": 500,
"display_name": "Jane's London Marathon"
}Providing charity_ids sets the charities for the fundraising page. Note, where multiple charities are specified, each charity will receive an equal share of the donations.
Inherit allocation from parent:
POST /api/fundraisings/create/456/
Authorization: Bearer <your_api_token>
Client-ID: 1234
Content-Type: application/json
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"charity_ids": ["Inherit"]
}Copies all Charity allocation records from the parent exactly, preserving percentshare values.
Without an event_id, the page is created as an independent fundraising page, not linked to any series. Title, content, and event date must be provided explicitly.
Endpoint: POST /api/fundraisings/create/
| Field | Type | Required? | Notes |
|---|---|---|---|
email |
string | Required | Creates a GiveWheel account if not already registered. Matched case-insensitively. |
first_name |
string | Required | Applied to a new account; added to existing account if blank. |
last_name |
string | Required | Applied to a new account; added to existing account if blank. |
title |
string | Required | The page title. |
content |
string | Required | Page description / body text. |
event_date |
date (YYYY-MM-DD) | Required | Main event / fundraising date. |
charity_ids |
array of strings | Required unless donorled_type="Unlimited"> |
Accepts Charity Commission IDs. Provide explicit IDs. IDs that don't exist on GiveWheel will return a 400 error. See the verify endpoint for a pre-flight bulk check. Note: Where creating a DonorLed page, behaviour depends on donorled_type - see DonorLed section. |
target |
integer | Optional | Fundraising target. Defaults to no target if omitted. |
hero_pic_url |
string (URL) | Optional | URL of a publicly accessible image to use as the page hero image. The image is downloaded, center-cropped to 16:9, resized to max 1920×1080, and compressed as JPEG. Must be publicly reachable and under 15 MB. Returns 400 if the URL is unreachable, not an image, or too large. |
display_name |
string | Optional | Name shown on the page. Defaults to "First Name, Last Name". |
event_start_date |
date (YYYY-MM-DD) | Optional | Used for pages with a date range. Date must be before the event_date. |
event_close_date |
date (YYYY-MM-DD) | Optional | When the page closes for donations. Defaults to event_date + 90 days if omitted. |
donorled_type |
string | Optional | "Unlimited", "Selective", or "Split". See DonorLed section below. |
POST /api/fundraisings/create/
Authorization: Bearer <your_api_token>
Client-ID: 1234
Content-Type: application/json
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"title": "Jane's Marathon Run",
"content": "I'm running 26.2 miles to raise money for a great cause!",
"event_date": "2026-10-04",
"event_close_date": "2026-10-11",
"charity_ids": ["1234567"],
"target": 1000
}event_close_date defaults to event_date + 90 days if omitted.
Note, where multiple charities are specified, each charity will receive an equal share of the donations.
DonorLed pages allow donors to choose which charity their donation goes to, rather than a fixed allocation. The donorled_type field controls the behaviour and determines how charity_ids is used.
donorled_type: "Unlimited"Donors can search and choose any charity on the platform. charity_ids is not required or used.
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"title": "Jane's Charity Run",
"content": "Donate and choose your own charity!",
"event_date": "2026-10-04",
"donorled_type": "Unlimited"
}donorled_type: "Selective"Donors choose from a pre-defined shortlist. charity_ids is required.
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"title": "Jane's Charity Run",
"content": "Choose from our three partner charities.",
"event_date": "2026-10-04",
"donorled_type": "Selective",
"charity_ids": ["1234567", "7654321", "9876543"]
}donorled_type: "Split" - or omit donorled_typeDonations are split equally between the specified charities and the donor's choice - 50% to each
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"title": "Jane's Charity Run",
"content": "Supporting two charities equally.",
"event_date": "2026-10-04",
"charity_ids": ["1234567", "7654321"]
}2 charities → 50% / 50%. 3 charities → 33.33% / 33.33% / 33.34%.
The API guards against accidental duplicates. If a page already exists for the same email address in the same series (or with the same title and event date for standalone pages), it returns 409 Conflict:
{
"error": "A fundraising page already exists for this user in this series.",
"hint": "To create a second page anyway, resubmit with \"override_duplicate\": true"
}To bypass, add "override_duplicate": true to your request body. Useful when the same participant legitimately needs two pages (e.g. two different events run by the same person).
{
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"charity_ids": ["1234567"],
"override_duplicate": true
}| Status | Meaning |
|---|---|
201 Created |
Page created. Returns the full fundraising page object. |
400 Bad Request |
Missing required fields, invalid email, unrecognised charity_id, event is not a series, or hero_pic_url could not be downloaded or processed. |
403 Forbidden |
Missing, expired, or read-only API token. |
404 Not Found |
The specified event_id does not exist. |
409 Conflict |
Duplicate page detected. Add "override_duplicate": true to proceed. |
POST /api/organisations/verify/
Before a bulk import, use this endpoint to check a list of charity IDs in one call.
For each ID it checks whether the charity is available for fundraising on GiveWheel.
Any IDs not found in either are returned in not_found — those will cause a 400 if passed to the create endpoint.
Requires the same write API token as the create endpoint. Maximum 100 IDs per request.
POST /api/organisations/verify/
Authorization: Bearer <your_api_token>
Content-Type: application/json
{
"charity_ids": ["1234567", "9876543", "0000000"]
}
// Response 200:
{
"found": ["1234567", "9876543"],
"not_found": ["0000000"]
}IDs in found are safe to use in the create endpoint. IDs in not_found are not recognised by GiveWheel or the Charity Commission and will need to be added manually.
/api/?limit=100&offset=0 for pagination.?time_since=YYYY-MM-DD where supported.error field.