Rest API

How to work with and use the GiveForms Rest API

The GiveForms API cannot be automatically enabled through your account at this time. If you're interested in enabling our Rest API for your GiveForms account, contact us at hello@giveforms.com.

Calling the GiveForms API

The GiveForms API uses basic authentication. Use your organization login email as your authorization username and the API Key as your password.

General format using cURL.

curl -X METHOD --user login@email.com:YOUR_API_KEY https://app.giveforms.com/{endpoint}

You can test the GiveForms API endpoint directly in a web browser.

https://login@email.com:API_KEY_XXX@app.giveforms.com/{endpoint}

API endpoints

Donations

Retrieve all the donations for your organization's account.

{GET} /api/v1/donations


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=18

Filters

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=XXXX

Your 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=XXX

Your 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

Rest API

Access this feature in GiveForms at:
Settings > Integrations

The GiveForms API cannot be automatically enabled through your account at this time. If you're interested in enabling our Rest API for your GiveForms account, contact us at hello@giveforms.com.

Calling the GiveForms API

The GiveForms API uses basic authentication. Use your organization login email as your authorization username and the API Key as your password.

General format using cURL.

curl -X METHOD --user login@email.com:YOUR_API_KEY https://app.giveforms.com/{endpoint}

You can test the GiveForms API endpoint directly in a web browser.

https://login@email.com:API_KEY_XXX@app.giveforms.com/{endpoint}

API endpoints

Donations

Retrieve all the donations for your organization's account.

{GET} /api/v1/donations


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=18

Filters

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=XXXX

Your 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=XXX

Your 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

Start Fundraising Today

Create a Free Account
Get up and running in 15 minutes