🙋 Supporter Use Cases
Examples of how to use the Enthuse API to get information on your Supporters
This document will explain some common examples of using the Enthuse API when pulling back data related to Supporters.
A Supporter is created on the Donations & Fundraising Platform when a donation is made or a fundraising page is created. They will be created with a unique 'supporterId'.
A Supporter will be updated with all of their new donation and fundraising activity.
Example of details for Supporters can be retrieved from the following endpoints:
- Retrieve a list of supporter records /supporter
- Retrieve an existing supporter record /supporter/{supporter_id}
For more detail see the Supporter Documentation
❓How can I see a supporter's single and recurring donations?
Within an Enthuse checkout, a donor can make a one off payment or schedule a donation for a personal, team, event or charity fundraising page.
If the donor has fundraised or donated to your charity previously it will link to the existing supporter otherwise it will create a new supporter.
This will also create a payment and schedule both linked to the supporter.
You are able to call the /supporter endpoint with relevant filters (if required) which will retrieve a list of newly created or updated supporters filtered by the supplied filters.
{
"status": 200,
"supporterPojoList": [
{
"supporterId": 1234,
"charityAccountGuid": "00000000-0000-0000-0000-000000000000",
"charityId": 123456,
"companyAccountGuid": null,
"companyId": 0,
"firstName": "firstName",
"lastName": "lastName",
"title": null,
"email": "[email protected]",
"isFund": false,
"isDonor": true,
"houseName": "56",
"address1": "Street",
"address2": "Greater London",
"town": "London",
"postcode": "SW1A 1AA",
"country": "United Kingdom",
"phone": null,
"billingHouseName": null,
"billingAddress1": null,
"billingAddress2": null,
"billingTown": null,
"billingPostcode": null,
"userGuid": null,
"join_date": "2022-11-10 16:18:31",
"last_donation_date": "2023-01-10 17:37:17",
"life_time_gift_aid": 0,
"fundraising_total": 0,
"full_name": "firstName lastName",
"country_code": "GB",
"currency_sign": "£",
"currency": "GBP",
"last_updated_at": "2023-01-10 17:37:43"
},
{
"supporterId": 1235,
"charityAccountGuid": "00000000-0000-0000-0000-000000000000",
"charityId": 123456,
...There are a few ways to link the supporter to the schedule.
One option is to link to the payment object then through to the schedule.
Calling the /payments endpoint with relevant date parameters will retrieve the corresponding payment.
You can tell what supporter the payment object is linked to with the field 'supporter_id' and linked to the schedule by the field 'fundraise_schedule_id'
{
"status": 200,
"paymentList": [
{
"payment_transaction_guid": "00000000-0000-0000-0000-000000000000",
"charity_account_guid": "00000000-0000-0000-0000-000000000000",
"company_account_guid": null,
"shared_campaign_guid": null,
"registrations_event_id": 0,
"registrations_order_id": 0,
"fundraise_event_page_id": 1234,
"fundraise_checkout_id": 12345,
"fundraise_payment_id": 12345,
"payment_method_reference": "ch_2M2ecF8KNXEifjA613uPgXV9",
"payment_system": "StripeConnect",
"first_name": "firstName",
"last_name": "lastName",
"transaction_type": "Payment",
"product_type": "Fundraising",
"payment_date": "2022-11-10 16:28:34",
"fundraise_page_or_team_page_ids": [
1234
],
"payment_type": "Donation",
"currency": "GBP",
"platform_fee": 0.68,
"gift_aid_fee": 0,
"service_fee": 0,
"payment_provider_fee": 0,
"amount_without_fees": 24.32,
"amount_with_fees": 25,
"gift_aid_amount": 0,
"donor_fee_covered_amount": 0,
"fee_model": "Gifting",
"is_submitted_to_hmrc_status": false,
"fundraise_schedule_id": 12345,
"parent_payment_transaction_guid": null,
"title": "",
"house_name": "56",
"address_line_1": "Street",
"address_line_2": "Greater London",
"town": "London",
"post_code": "SW1A 1AA",
"country_code": "GB",
"supporter_id": 1234,
"is_guest": true,
"is_anonymous": false,
"donation_message": null,
"email": "[email protected]",
"checkoutReferenceCode": null,
"purchaseInformation": null
},
{
"payment_transaction_guid": "00000000-0000-0000-0000-000000000000",
"charity_account_guid": "00000000-0000-0000-0000-000000000000",
"company_account_guid": null,
"shared_campaign_guid": null,
...You are then able to call the schedules/{schedule_Id} endpoint with the 'fundraise_schedule_id' field or search to get the schedule information.
{
"createdOn": "2022-11-10 16:18:40",
"endDate": null,
"lastUpdatedAt": "2023-01-10 17:37:30",
"supporterId": 1234,
"schedulesId": 12345,
"amount": 10,
"email": "[email protected]",
"status": "Active",
"frequency": "Monthly",
"pfId": 1234,
"teamId": 0,
"eventPageId": 1234,
"campaignGuid": null,
"charityAccountGuid": "00000000-0000-0000-0000-000000000000",
"charityId": 319814,
"companyId": 0,
"companyAccountGuid": "00000000-0000-0000-0000-000000000000"
}❓How can I see a supporter's marketing preferences?
When a supporter creates a page or makes a donation they will be asked for their marketing preferences.
After calling the supporters endpoint, you are able to use the field 'supporterId' within the 'supporter_Id' parameter for the /marketingPreferences/{supporter_id} endpoint, which will return you the supporter's marketing preferences.
This is updated each time a supporter is requested to enter their marketing preferences, meaning that only the most recently answered preferences are returned.
{
"answeredAt": "2022-02-17 12:07:16",
"supporterId": 1234,
"charityAccountGuid": "00000000-0000-0000-0000-000000000000",
"emailOptIn": false,
"phoneOptIn": false,
"smsOptIn": false,
"postOptIn": false,
"charityId": 319814,
"allowedToContact": false,
"permissionStatement": "We'd love to keep you up to date with our projects and fundraising activities. Please let us know if it's okay to contact you. We'll never share your data.",
"campaignGuid": null
}❓How can I see a supporter's supporter custom codes?
On the Donations & Fundraising Platform Custom Codes can be set to add a customisable value to Supporters. You can customise the names of the fields and assign the values either one by one or many at once.
With the Enthuse API you are able to get the custom code data you have set for your supporters
To get the custom code for a specific supporter you can match the field 'supporterId' to the 'supporter_Id' parameter for the /supporterCustomCodes endpoint, which will return the custom codes associated with your supporter.
{
"message": "string",
"status": 0,
"supporterCustomCodePojoList": [
{
"created_date": "2023-01-23T14:57:24.357Z",
"modify_date": "2023-01-23T14:57:24.357Z",
"custom_code_id": 7236487,
"supporter_id": 1234,
"value": "string",
"name": "string"
}
],
"totalCount": 1
}Updated about 2 months ago