Donation Data Structure

You can view the data structure and available fields for a Donation resource by requesting a New Donation.

Request

Response

<?xml version="1.0" encoding="UTF-8"?>
<donation>
  <amount-in-cents type="integer">0</amount-in-cents>
  <bank-name nil="true"></bank-name>
  <bank-number nil="true"></bank-number>
  <batch-date type="datetime" nil="true"></batch-date>
  <batch-number nil="true"></batch-number>
  <check-date type="date" nil="true"></check-date>
  <check-number nil="true"></check-number>
  <completed-at type="datetime" nil="true"></completed-at>
  <created-at type="datetime" nil="true"></created-at>
  <currency nil="true"></currency>
  <donation-type-id type="integer" nil="true"></donation-type-id>
  <legacy-id nil="true"></legacy-id>
  <memo nil="true"></memo>
  <payment-status nil="true"></payment-status>
  <persona-id type="integer" nil="true"></persona-id>
  <pledge-id type="integer" nil="true"></pledge-id>
  <received-on type="date">2011-10-13</received-on>
  <source-id type="integer" nil="true"></source-id>
  <transaction-fee-in-cents type="integer" nil="true"></transaction-fee-in-cents>
  <transaction-id nil="true"></transaction-id>
  <updated-at type="datetime" nil="true"></updated-at>
  <amount type="Money">0.00</amount>
  <transaction-fee type="Money">0.00</transaction-fee>
  <splits type="array">
    <split>
      <amount-in-cents type="integer" nil="true"></amount-in-cents>
      <currency type="yaml" nil="true"></currency>
      <donation-id type="integer" nil="true"></donation-id>
      <fund-id type="integer" nil="true"></fund-id>
      <memo nil="true"></memo>
      <amount type="yaml" nil="true"></amount>
    </split>
  </splits>
</donation>

Listing Donations

Request

Response

<?xml version="1.0" encoding="UTF-8"?>
<donations type="array" current_page="1" per_page="50" total_entries="2955">
  <donation>
    ...
  </donation>
</donations>

Get a Specified Donation by Id

Request

Response

<?xml version="1.0" encoding="UTF-8"?>
<donation>
  ...
</donation>

Create a Donation

Before creating a donation, look at the available attributes by requesting "/people/new.(xml|json)" (above).

Request

Response

<?xml version="1.0" encoding="UTF-8"?>
<donation>
  ...
</donation>

Required Attributes

The following attributes are required for every donation:

• Person Id (persona_id)
• Amount or “amount-in-cents”. This can be zero, or negative, to indicate a refund. If you specify an “amount”, specify it as a floating-point value like “12.34”. If you provide “amount-in-cents”, then send it as a multiple of 100, like “1234”.
• Fund Id
• Source Id
• Donation Type Id
• Received Date

Person

Every donation must belong to a person. The person is specified through the "persona_id" attribute. The person must already exist in the database in order to pass the persona_id.

Find or Create Person (beta)

There is an experimental method called "find-or-create-person". You can provide a Person resource right in the donation API, as shown below. Donor Tools will attempt to match an existing person by name, address, and email address. If an exact match is not found, then a new record will be created.

<?xml version="1.0" encoding="UTF-8"?>
<donation>
  <find-or-create-person>
    <names type="array">
      <name>
        <first-name>Fooz</first-name>
        <last-name>Ball</last-name>
      </name>
    </names>
    ... look at the People API for a complete list of attributes that you can provide
  </find-or-create-person>
</donation>

Note: Because this method looks for exact matches, there is a strong possibility of ending up with duplicate donors. These can be merged together with our merge tool.

Update a Donation

To make sure that you have the most recent data for a Donation resource, it is usually a good idea to GET the resource before attempting to update it. Then, you can simply modify the XML attributes as needed and send it back. Alternatively, you can construct an XML file using the structure shown above.

Request

<?xml version="1.0" encoding="UTF-8"?>
<donation>
  ...
</donation>

Response

Delete a Donation

Request

Response