Integrate with Fundraiser API

The Fundraiser API allows a fundraising website to integrate with Facebook to extend the effectiveness, reach and visibility of their campaigns. Fundraising pages on the fundraising website can be mirrored on Facebook allowing people to raise money on their Facebook Fundraiser, while keeping donation information in sync between the mirrored pages.

To plan how the Fundraiser API can fit into your existing site, visit our planning guide here: https://developers.facebook.com/docs/fundraiser-api/plan

Graph API endpoints to manage fundraisers on Facebook:

• /me/fundraisers - Create a fundraiser
• /{fundraiser-id} - Get or update a fundraiser
• /{fundraiser-id}/end_fundraiser - End a fundraiser
• /{fundraiser-id}/donations - Get the list of donations made on Facebook from an existing fundraiser
• /{fundraiser-id}/external_donations - Post and delete donations made on the external fundraiser site to keep data in sync with Facebook
• Webhook subscription - Get notified in real-time about donations made on Facebook.

Getting Access

To submit for Fundraiser API access, go to the app dashboard, select your app, add the Fundraisers product, click Set Up and follow the instructions. Once your app is approved, your app will have access to the manage_fundraisers permission, which is required to call the Fundraiser API endpoints below.

Create a fundraiser

To create a new fundraiser on behalf a user, make a POST request to /me/fundraisers with a user access token. Making a GET request to this endpoint will list all fundraisers created by your app for the given user.

Request Fields

• The user access token must belong to an actual Facebook user. Creating a fundraiser cannot be performed by a test user.
• goal_amount must be a positive integers. For currencies with cents like USD, round up the value to an integer and then multiply by 100. For example, $123.45 should be converted to 12400. This is necessary because we only allow users to set goal amounts in whole units. When posting external donations to Facebook, you don't need to round the amount.
• If you don't pass the cover_photo, the fundraiser will display a default cover photo.
• To pass the cover_photo you need to upload the image as multipart/form-data.
• Facebook converts the end_time to 11:59pm in the fundraiser creator's timezone.

Example Request

curl -X POST -H "Content-Type: application/json" -d '{
  "page_id": 12345,
  "name": "Test Fundraiser",
  "description": "The description for Test Fundraiser",
  "goal_amount": 100000,
  "currency": "USD",
  "end_time": 1501784952,
  "external_id": "ABC123",
  "fundraiser_type": "person_for_charity",
  "external_fundraiser_uri": "https://secure.info-komen.org/site/TR?fr_id=6847&pg=personal&px=123",
  "external_event_name": "2017 Komen DC Race for the Cure",
  "external_event_uri": "https://secure.info-komen.org/site/TR?fr_id=6847&pg=entry",
  "external_event_start_time": 1504970131
}' "https://graph.facebook.com/v2.8/me/fundraisers?access_token=USER_ACCESS_TOKEN"

Response

If the request succeeds, the response object will contain a single field id with the unique identifier of the created object.

Example Response

{
  "id": "1234567"
}

Update a fundraiser

You can edit a fundraiser by issuing a POST request to /{fundraiser-id} with a user or app access token.

Here are the fields that can be updated: name, description, goal_amount, end_time, external_event_name, external_event_start_time, external_fundraiser_uri, external_event_uri, external_id.

End a fundraiser

While ending a fundraiser is generally controlled by the user on Facebook, there may be situations where you may need to end all fundraisers to stop receiving donations from Facebook. You can do this by issuing a POST request to /{fundraiser-id}/end_fundraiser with a user or app access token.

Get donations

To list all donations made on Facebook send a GET request to /<fundraiser_id>/donations with a user or app access token. As any other Graph API endpoint, you can user the fields parameter to specify a comma separated list of fields you want to the response to contain.

You can also get donations data in real-time by creating a Webhook subscription.

Request Fields

Example Request

curl "https://graph.facebook.com/v2.8/<fundraiser_id>/donations?access_token=USER_ACCESS_TOKEN&limit=1&fields=amount_received,donation_time,donor_id_hash,fundraiser,id,currency,payment_id"

Response Fields

The following fields may be included in the response for each object in the data array:

Example Response

{
  "data": [
    {
      "amount_received": 500,
      "donation_time": "2017-03-01T16:03:08+0000",
      "donor_id_hash": "BA1C...bSA",
      "fundraiser": {
        "id": "1234567"
      },
      "id": "987654321",
      "currency": "USD",
      "payment_id": "135792468"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFI...FR",
      "after": "QVFI...FR"
    }
  }
}

Create and delete external donations

To update the counter on the Facebook Fundraiser, you need to let Facebook know about donations happening on your site. You can do this by making a POST request to /<fundraiser_id>/external_donations with an app access token.

The amount_received must be in the same currency that you set when creating the fundraiser. Unlike the goal_amount, you should not round this number even though the Fundraiser page does not show cents.

For example, if you pass a donation of $10.20 as 1020, then the progress UI will show $10. If you then pass another donation of $9.80, the total will correctly be added to show $20.

If you need to delete the donation, issue a DELETE request to the Graph API node ID that it was returned to you when creating the donation.

There is no support for updating an existing external donation. If you need to do so, you can delete the external donation and create a new one with the updated information.

Example Requests

curl -X POST -H "Content-Type: application/json" -d '{
  "amount_received": 4000,
  "currency": "USD",
  "donation_id_hash": "3857768956349",
  "donor_id_hash": "4587387354",
  "donation_time": 1488387995
}' "https://graph.facebook.com/v2.8/<fundraiser_id>/external_donations?access_token=APP_ACCESS_TOKEN"

curl -X DELETE "https://graph.facebook.com/v2.8/<external_donation_id>?access_token=APP_ACCESS_TOKEN"

Response

If the POST request succeeds, the response will contain a single field id with the unique identifier of the new Graph API object. This is the id that you can use to delete the external donation.

Example Response

{
  "id": "9876543"
}

Parameters

Get real-time donation data

To keep donation data in sync on your platform, Facebook can send real-time updates to your servers via a webhook. To do this, create a webhook subscription for the Application object's fundraiser_donations field. Refer to the Webhook documentation to learn how to setup a webhook subscription for your app.

Facebook will send an HTTPS POST request to your callback URL when someone makes a donation to a fundraiser created by your app. The body of the request will contain a JSON payload as described in the Webhook documentation, including these donation fields:

Example Request

[
  {
    "object": "application",
    "entry": [
      {
        "id": "9186349565458",
        "time": 1478311580,
        "changes": [
          {
            "field": "fundraiser_donations",
            "value": {
              "id": 1323410515135,
              "fundraiser_id": 41312314512132,
              "amount_received": 2000,
              "currency": "USD",
              "donation_time": "2019-06-11T16:03:08+0000",
              "donor_id_hash": "BARDSADm0341341kuv...",
              "payment_id": 12312312123
            }
          }
        ]
      }
    ]
  }
]

FAQ

You can find answers to commonly asked questions in our FAQ at https://developers.facebook.com/docs/fundraiser-api/faq