Rest API
How to work with and use the GiveForms Rest API
Enable the Rest API by going to Settings / Integrations in your GiveForms account and clicking Enable Rest API.
Calling the GiveForms API
The GiveForms API uses basic authentication. Use your organization ID as your username and the API Key as your password.
General format using cURL.
curl -X METHOD --user ORG_ID:YOUR_API_KEY https://app.giveforms.com/{endpoint}You can test the GiveForms API endpoint directly in a web browser.
https://ORG_ID:YOUR_API_KEY@app.giveforms.com/{endpoint}API endpoints
Donations
Retrieve all the donations for your organization's account.
Below is an example of the output from our API
{
"id": 00000,
"email": "example@yahoo.com",
"form_name": "End World Hunger",
"first_name": "James",
"last_name": "Parker",
"address": "728 Maple Ave",
"city": "Raleigh",
"state": "North Carolina",
"postcode": "27601",
"country": "United States",
"donation_type": "credit_card",
"payment_type": "visa",
"payment_charge_id": "ch_5JcAeCLw6pPC256a1DgD44Fv",
"status": "refunded",
"amount": "5.0",
"formatted_amount": "$5.00",
"currency": "usd",
"converted_amount": "5.0",
"formatted_converted_amount": "$5.00",
"converted_currency": "USD",
"donation_date": "2021-09-21T15:12:55.644Z",
"anonymous": false,
"recurring": false,
"last4": "0555",
"exp_year": 2024,
"exp_month": 9,
"timezone": "UTC",
"processing_fee": 0.41,
"formatted_processing_fee": "$0.41",
"app_fee": 0.1,
"formatted_app_fee": "$0.10",
"fee_covered": "No",
"last_updated_at": "2021-11-04T19:55:07.530Z",
"questions":
[
{
"question_type": "check",
"question": "",
"answer": false
}
],
"utm_source": "",
"utm_medium": "",
"utm_campaign": "",
"utm_content": "",
"donation_honor":
{
"honoree_name": "Wendy Parker,
"tribute_type": "Memory",
"notification_preference": "Mail",
"recipient_name": "Peter Parker",
"recipient_email": "",
"recipient_country": "United States",
"recipient_state": "North Carolina",
"recipient_city": "Raleigh",
"recipient_zipcode": "27613",
"recipient_address": "8910 Elm St",
"recipient_message": "Love you!"
}
},
Filtering API Results
Ordering
GiveForms API endpoints are in ascending order.
Pagination
All GiveForms API endpoints support pagination. Use page and per_page parameters to adjust the number of results returned.
The default page size is 100 with a maximum 100 allowed. If this value exceeds the maximum, pagination will revert to the default.
{GET} /api/v1/donations?page=2&per_page=18Filters
Use email to get donations based on a donor's email address.
{GET} /api/v1/donations?email=XXXXXXX
Use first_name to get donations by a donor's first name.
{GET} /api/v1/donations?first_name=XXXXXXX
Use last_name to get donations by a donor's last name.
{GET} /api/v1/donations?last_name=XXXXXXX
Use campaign_id to get donations by campaign id.
{GET} /api/v1/donations?campaign_id=XXXXYour GiveForms Campaign ID can be found in the Campaigns section of your account. After opening a campaign, the number at the end of the URL is your campaign ID.
Use id to filter donations by GiveForms donation id.
{GET} /api/v1/donations?id=XXXYour GiveForms Donation ID can be found in the Donations section of your account. After opening a donation, the number at the end of the URL is your donation ID.
Combining Filters
You may combine the filters described above, taking into account supported endpoints for a specific filter.
{GET} /api/v1/donations?page=3&per_page=20&campaign_id=XX&&email=test@test.com
