Skip to main content

Introduction to the API

Jeremy Tobias
Updated

GiveEasy API

If you need to pull live data from GiveEasy to import into your CRM or a 3rd party system, you may be able to use the GiveEasy public API.

Endpoints use the https://www.odata.org/documentation/ standard to navigate collections. Please make sure you are familiar with the OData syntax if you plan to use the API.

 

Before You Begin

  1. You will need a Giveeasy Account and API Key/Secret to get access. Contact support@giveeasy.org to register.
  2. The API only allows limited access to the data available from the export/CSV download. If you are doing analysis or financial reporting, it is recommended to use the CSV export tool.
  3. The API is read-only (as of version 1.0) - you can pull data from GiveEasy with a GET but we don't support POST/PUT/DELETE, etc.
  4. Endpoints support OData query syntax as much as possible, but some endpoints may not support all operations.

 

Authorization

  1. Contact support@giveeasy.org to enable API access on your account.
  2. You will receive an HTTP Basic Auth secret that can be used for all endpoint requests.
    1. Set this as your HTTP Basic Authorization Header:mceclip0.png

Hosts

  1. All API services are located at 
    1. https://api.giveeasy.org/odata/...
  2. Client requests must use HTTPS with TLSv1.2 or higher

Versions

  1. API Requests should include a version number in the path - e.g. at 
    1. https://api.giveeasy.org/odata/v1.0/...
    2. Versions may be specified through path (odata/v1.0/) or with a query parameter (?api-version=1.0)
  2. If the version segment of the path is missing, the API will default to "latest" (which might include experimental/unreleased versions)
  3. Version Path Release Date
    1.0 /v1.0/ 2021-06-01
         

Endpoints

Donations (v1.0+)

https://api.giveeasy.org/odata/{v}/donations

Gets information about successful Donations and Pledges made for your Appeals. Includes all custom fields configured for your Charity.

Path: /donations

 

Example 1:

Request

GET https://api.giveeasy.org/odata/v1.0/donations?$top=100

Get information about the last 100 donations

Response

{
"@odata.context": "https://api.giveeasy.org/odata/v%7Bversion:apiVersion%7D/$metadata#Donations/GiveEasy.%3C%3Ef__AnonymousType1_34OfGuid_DateTime_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_Decimal_Decimal_Decimal_Decimal",
"value": [
{
"@odata.type": "#GiveEasy.<>f__AnonymousType1_34OfGuid_DateTime_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_Decimal_Decimal_Decimal_Decimal",
"compounduuid": "281aadbd-5991-4019-9f78-00019df75874",
"created": "2021-06-20T10:36:14.1970938Z",
"email": "fred@bedrock.com",
"firstname": "Fred",
"lastname": "Flintstone",
"currency": "AUD",
"transaction": "Success",
"appealtitle": "Waterbuffalo Lodge Fundraiser",
"appealkey": "waterbuffalo-lodge-fundraiser",
"comment_anonymous": "False",
"comment_url": "https://giveeasy.org/fd3a9dc8-3562-4f50-aebe-62f78465f8f8",
"comment_message": "",
"custom_id": "",
"custom_mobile": null,
"context_key": "",
"group_title": "",
"group_key": "",
"custom_no": null,
"custom_country": null,
"custom_street": null,
"custom_suburbtown": null,
"custom_state": null,
"custom_postcode": null,
"custom_phone": null,
"comment_forum": "giveeasy-test",
"custom_title": "AdditionalGiveEasyDonors",
"givingid": 1436952.00,
"charityid": 123.00,
"amount": 15.00,
"multiplier": 2.00
},
{
"@odata.type": "#GiveEasy.<>f__AnonymousType1_34OfGuid_DateTime_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_Decimal_Decimal_Decimal_Decimal",
"compounduuid": "281aadbd-5991-4019-9f78-00019df75874",
"created": "2021-06-20T10:36:14.1970938Z",
"email": "betty@rubble.ru",
"firstname": "Betty",
"lastname": "Rubble",
"currency": "AUD",
"transaction": "Success",
"appealtitle": "Waterbuffalo Lodge Fundraiser",
"appealkey": "waterbuffalo-lodge-fundraiser",
"comment_anonymous": "False",
"comment_url": "https://giveeasy.org/fd3a9dc8-3562-4f50-aebe-62f78465f8f8",
"comment_message": "",
"custom_id": "",
"custom_mobile": null,
"context_key": "",
"group_title": "",
"group_key": "",
"custom_no": null,
"custom_country": null,
"custom_street": null,
"custom_suburbtown": null,
"custom_state": null,
"custom_postcode": null,
"custom_phone": null,
"comment_forum": "giveeasy-test",
"custom_title": "AdditionalGiveEasyDonors",
"givingid": 1436953.00,
"charityid": 123.00,
"amount": 60.50,
"multiplier": 2.00
}]
}

Example 2:

Request

GET https://api.giveeasy.org/odata/v1.0/donations?$filter=
created gt 2018-07-01T05:21:00-00:00 
AND firstname eq 'Fred' 
AND lastname eq 'Flintstone'

Get all of Fred Flintstone's donations since 2018-07-01 

Response

{
"@odata.context": "https://api.giveeasy.org/odata/v%7Bversion:apiVersion%7D/$metadata#Donations/GiveEasy.%3C%3Ef__AnonymousType1_34OfGuid_DateTime_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_Decimal_Decimal_Decimal_Decimal",
"value": [
{
"@odata.type": "#GiveEasy.<>f__AnonymousType1_34OfGuid_DateTime_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_String_Decimal_Decimal_Decimal_Decimal",
"compounduuid": "281aadbd-5991-4019-9f78-00019df75874",
"created": "2021-06-20T10:36:14.1970938Z",
"email": "fred@bedrock.com",
"firstname": "Fred",
"lastname": "Flintstone",
"currency": "AUD",
"transaction": "Success",
"appealtitle": "Waterbuffalo Lodge Fundraiser",
"appealkey": "waterbuffalo-lodge-fundraiser",
"comment_anonymous": "False",
"comment_url": "https://giveeasy.org/fd3a9dc8-3562-4f50-aebe-62f78465f8f8",
"comment_message": "",
"custom_id": "",
"custom_mobile": null,
"context_key": "",
"group_title": "",
"group_key": "",
"custom_no": null,
"custom_country": null,
"custom_street": null,
"custom_suburbtown": null,
"custom_state": null,
"custom_postcode": null,
"custom_phone": null,
"comment_forum": "giveeasy-test",
"custom_title": "AdditionalGiveEasyDonors",
"givingid": 1436952.00,
"charityid": 123.00,
"amount": 15.00,
"multiplier": 2.00
}]
}

F.A.Q.

  • Why do I get an empty body in my HTTP response?
    • If the response body from a request is too long, the server will close the stream before the output has finished writing. Try using $top and $skip to limit the number of items returned in a single request.
  • Why do I sometimes get a 302 instead of a 200 response?
    • A 302 indicates a cache miss and the result isn't ready to be written yet. Following the 302 Location will reload the result from the cache when it has been loaded.
  • Can I see the Fees/Gross/Net Amounts in the API?
    • GiveEasyFee isn’t part of the API, but the client can calculate it themselves off their fixed base rate
  • Where is the "Organization Name" field?

    • OrganizationName shown in the CSV is an alias of custom_organization_name (a custom field if you’ve defined it) in the API

 

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk