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

You can create a donation and simultaneously look up the correct donor with one API request. Simply pass the Person information through a "find-or-create-person" node. Donor Tools will try to look up the existing record; if one isn't found then it will be created.

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

  <splits type="array">
    <split>
      <amount type="yaml">100</amount>
      <fund-id type="integer">12345</fund-id>
      <memo>Split memo goes here</memo>
    </split>
  </splits>
  <memo>Donation memo goes here.</memo>
  <donation-type-id type="integer">1</donation-type-id>
  <received-on type="date">2011-10-13</received-on>
  <source-id type="integer">12345</source-id>

  <find-or-create-person>
    <full-name>Joe Donor</full-name>
    <email-address>joedonor@example.com</email-address>
    <street-address>123 4th St</street-address>
    <city>Austin</city>
    <state>Texas</state>
    <postal-code>78777</postal-code>
    <phone-number>(555) 555-1234</phone-number>
  </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