Developer Blog Series: POST Gift Spotlight

Cameron Beacham

POST gift functionality is finally here! The Gift (Create) endpoint was highly requested across all of our developer feedback channels, and with its recent release, we want to call out some information to help you get started.

 

Several properties are required to successfully create a gift. You need to provide the amount, type, constituent_id, gift_splits, post_date, and payments properties, and you can also provide additional optional properties. Most properties are straightforward, but some require supplemental calls to other endpoints in the Gift API and Fundraising API.

 

To illustrate how the Gift (Create) endpoint works, let's break down a simple call to create a gift. We want to add a $20 Halloween gift from Robert Hernandez to our sample database, so we start by specifying the amount, post_date, and Robert Hernandez’s constituent_id.

 

{

    "amount": {

        "value": 20.00

    },

    "constituent_id": 280,

    "post_date": "2017-10-31T00:00:00"

}

 

Note that post_date is required even if the gift is not yet posted. However, if you set the optional post_status property to “donotpost,” then post_date must be null.

 

Next, we need to specify the type. The Gift entity reference lists all valid gift types, but the Gift (Create) endpoint currently only supports “donation.” As we add support for additional gift types, we will update the Gift API changelog.

 

{

    "amount": {

        "value": 20.00

    },

    "constituent_id": 280,

    "post_date": "2017-10-31T00:00:00"

    "type": "donation"

}

 

We also need the payments property to indicate a payment method. The Gift entity reference lists all valid payment methods, but the Gift (Create) endpoint currently only supports “cash,” "creditcard," "personalcheck," "directdebit," and "other.” The endpoint also supports only one payment entity per gift at this time. For this example, let’s specify cash as the payment method.

 

{

    "amount": {

        "value": 20.00

    },

    "constituent_id": 280,

    "post_date": "2017-10-31T00:00:00"

    "type": "Donation",

    "payments": [

        {

            "payment_method": "cash"

        }

    ]

}

 

Finally, we need to specify the gift_splits. All gifts are required to have one or more gift splits that add up to the total gift amount. Additionally, all gift splits are required to have a fund_id specified. We could also specify campaign or appeal IDs to associate with the gift split, but those fields are not required to create a gift split on the gift.

 

To create a basic gift split, we specify an amount and the identifier of a fund to associate with the gift split. To find the fund ID, we can call the Fund list endpoint in the Fundraising API. For our example, we’ll use the ID for the Natural Disaster Relief Fund in the sample database.

 

{

    "amount": {

        "value": 20.00

    },

    "constituent_id": 280,

    "post_date": "2017-10-31T00:00:00",

    "type": "Donation",

    "payments": [

        {

            "payment_method": "cash"

        }

    ],

    "gift_splits": [

        {

            "amount": {

                "value": 20.00

            },

            "fund_id": "6"

        }

    ]

}

 

After we call the Gift (Create) endpoint, it returns an ID for a new gift!

{

   "id": "3908"

}

 

In addition to the required properties we describe here, several optional properties are also available when you create a gift. For information about these properties, check out the Gift (Create) endpoint reference. One last thing to note is that the Gift (Create) endpoint does not currently support gift aid information for gift splits.

 

We’re really excited that this POST functionality is finally available in the Gift API, and we hope that you are too!