<p><span style="line-height: normal;"> </span></p>
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 6px; margin-left: 0px; padding-top: 1px; padding-right: 0px; padding-bottom: 1px; padding-left: 0px; color: #333333; line-height: 1.4em; clear: left; font-size: 1em; text-align: left;"><strong style="color:red">The Donor Tools API is a beta product and is subject to the <a href="http://www.donortools.com/about/api_license">API License Agreement</a>. </strong></p>
<p> </p>
<h1>Beta</h1>
<p>The Donor Tools API is a beta program. This means that it's available and functional, but it may not be complete. You may encounter errors or missing features. </p>
<p> </p>
<h1>Example App</h1>
<p>Check out our dead-simple example app on Github: <a href="http://github.com/artofmission/Donor-Tools-Consumer/">http://github.com/artofmission/Donor-Tools-Consumer/</a>. The example app might give you some ideas about how you can interact with our API. </p>
<p> </p>
<h1>REST</h1>
<p>The Donor Tools API uses <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST</a> exclusively. </p>
<p> </p>
<h1>Authentication</h1>
<p>Donor Tools uses HTTP Basic authentication. Every request must include the Authorization HTTP header.</p>
<p> </p>
<h2>API User</h2>
<p>You'll need to sign up for a Donor Tools account in order to use the API. If you don't already have a Donor Tools account, you can get one by going to <a href="http://www.donortools.com/signup">www.donortools.com/signup</a>.</p>
<p>Donor Tools' auditing feature logs each and every action for your account. Thus, if you provide your own username and password for the API (not recommended), all actions through the API will appear as being committed by you. We recommend creating a separate API user to provide finer grained reporting detail. This technique also helps protect your personal authentication parameters, as you can provide a different username and password. </p>
<h3>Example</h3>
<pre>curl -u my-user@example.com:it2at9yags https://demo.donortools.com/donations.xml</pre>
<p> </p>
<h1>SSL</h1>
<p>All requests must be made over SSL (port 443).</p>
<p> </p>
<h1>Pagination</h1>
<p>Most GET #index methods are paginated. The XML response will include pagination metadata. You can specify the page you want very simply by passing the <em>page</em> parameter in your request. </p>
<h3>Example</h3>
<pre> <current_page type="integer">1</current_page>
<per_page type="integer">100</per_page>
<total_entries type="integer">1266</total_entries></pre>
<h3>Rails & ActiveResource</h3>
<p>Rails' built-in ActiveResource expects the results to return an array, but Donor Tools' API returns a collection that includes pagination metadata. We recommend using <a href="http://github.com/artofmission/will_paginate/">the artofmission branch of the will_paginate plugin</a>, which will automatically parse the results into an ActiveResource collection object, complete with metadata. </p>
<p> </p>
<h1>Available Resources</h1>
<p>Most resources are available via REST simply by attaching ".xml" to the URL. Try it with your web browser! For example, if you're viewing a donation at /donations/1, simply change the URL to /donations/1.xml to see the XML output in your browser. </p>
<h2>Personas</h2>
<p>Personas are the backbone of recordkeeping in Donor Tools. A persona can have many donations. </p>
<h2>Donations</h2>
<p>A donation belongs to a persona. Every donation must have one or more splits. A donation also may have one source. Each split must have one fund. </p>
<h2>Sources</h2>
<p>Sources describe where a donation is coming from. Sources are frequently used to represent fundraising campaigns or specific mailings. </p>
<h2>Funds</h2>
<p>Funds describe where a donation split is going to. Funds often correspond with an organization's programs. </p>
2009-05-18T16:11:42-07:00
api
47417
299
36961
true
false
false
true
0
Ryan Heneise
54137
API Introduction
2009-06-25T19:27:10-07:00
<p><strong style="color:red">The Donor Tools API is a beta product and is subject to the <a href="http://www.donortools.com/about/api_license">API License Agreement</a>. </strong></p>
<p>Personas is a simple REST resource supporting GET, POST, PUT, and DELETE.</p>
<h2>Usage</h2>
<p><span style="line-height: normal; "></span></p>
<pre style="margin-top: 0px; margin-right: 0px; margin-bottom: 10px; margin-left: 0px; padding-top: 1em; padding-right: 1em; padding-bottom: 1em; padding-left: 1em; background-color: #f1f7ee; color: #518f2a; font: normal normal normal 0.8em/normal 'Lucida Console', monospace; overflow-x: auto; ">curl -u <a href="mailto:user@example.com">user@example.com</a>:useagoodpassword <a href="http://demo.donortools.net/donations?range=all_dates">http://demo.donortools.net/</a>personas.xml</pre>
<p> </p>
<h3>Get All Personas</h3>
<p><strong>GET /personas.xml</strong></p>
<h4>Response</h4>
<pre><donations type="collection">
<current_page type="integer">1</current_page>
<per_page type="integer">100</per_page>
<total_entries type="integer">1266</total_entries>
<donation>
...
</donation>
</donations></pre>
<h3>Sorting</h3>
<p>You can sort personas by passing the "order" parameter - for example - "personas.xml?order=name". You can also pass a "direction" parameter, either "ASC" or "DESC". Possible values for the "order" parameter are name, address, donations, most_recent_donation, email_address, company, and added. </p>
<p> </p>
<h1>POST: Create a Persona</h1>
<p><strong>POST /personas.xml</strong></p>
<pre><?xml version="1.0" encoding="UTF-8"?>
<persona>
<name>Person From Webservice</name>
<organization-id type="integer">10001</organization-id>
</persona>
</pre>
<div><span style="font-family: 'Lucida Console', monospace; color: #518f2a; font-size: x-small;"><span style="font-size: 10px; white-space: pre;"><br /></span></span></div>
<p> </p>
2009-05-20T14:38:53-07:00
47417
262
37359
false
false
false
true
0
Ryan Heneise
54137
Personas API
2009-07-14T09:25:08-07:00
<p style="margin-top: 0px; margin-right: 0px; margin-bottom: 6px; margin-left: 0px; padding-top: 1px; padding-right: 0px; padding-bottom: 1px; padding-left: 0px; color: #333333; line-height: 1.4em; clear: left; font-size: 1em; text-align: left;"><strong style="color:red">The Donor Tools API is a beta product and is subject to the <a href="http://www.donortools.com/about/api_license">API License Agreement</a>. </strong></p>
<p>Donations is a simple REST resource supporting GET, POST, PUT, and DELETE.</p>
<h2>Notes</h2>
<ul>
<li>Amounts are always expressed in cents. So "$100.00" would be stored as an integer 10000. </li>
<li>Every donation must have at least one split. </li>
</ul>
<h1>GET a List of Donations</h1>
<h4>GET /donations.xml</h4>
<p>Returns a list of recent donations. </p>
<h4>Example Usage</h4>
<p><span style="line-height: normal; "> </span></p>
<pre style="margin-top: 8px; margin-right: 8px; margin-bottom: 10px; margin-left: 8px; padding-top: 4px; padding-right: 4px; padding-bottom: 4px; padding-left: 4px; color: #518f2a; font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 10px; background-color: #f1f7ee; font: normal normal normal 0.8em/normal 'Lucida Console', monospace; overflow-x: scroll; ">curl -u user@example.com:useagoodpassword http://demo.donortools.net/donations?range=all_dates</pre>
<h4>Response</h4>
<pre><donations type="collection">
<current_page type="integer">1</current_page>
<per_page type="integer">100</per_page>
<total_entries type="integer">1266</total_entries>
<donation>
<splits type="array">
<split type="DonationSplit">
<cents type="integer">12500</cents>
...
</split>
</splits>
</donation>
...
</donations>
</pre>
<h4>Parameters</h4>
<p><strong>(no parameters)</strong>: Requesting /donations.xml with no parameters automatically returns donations from the current month in all funds from all sources. </p>
<p><strong>range</strong>: (today|week|month|quarter|year|all_dates). Query donations in the specified range. Combine with timeframe for this or last range. You can also specify a custom date range by sending <strong>range[from]</strong> and <strong>range[to]</strong></p>
<p><strong style="padding: 0px; margin: 0px;">timeframe</strong>: (this|last). Combine with range to query specific timeframes. For example this month or last month. </p>
<p><strong>fund_id</strong>: Query donations in the specified fund. </p>
<p><strong>source_id</strong>: Query donations from the specified source. </p>
<h1>PUT: Update a Donation</h1>
<p><span style="line-height: normal;"> </span></p>
<h4 style="margin-top: 12px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; font-size: 12px; color: #555555; padding: 0px;">PUT /donations/123.xml</h4>
<pre><?xml version="1.0" encoding="UTF-8"?>
<donation>
<id type="integer">110172</id>
<organization-id type="integer">10001</organization-id>
<persona-id type="integer">121635</persona-id>
<source-id type="integer">304</source-id>
<received-date type="date">2009-06-11</received-date>
<donation-type-id type="integer">1</donation-type-id>
<memo>A memo about this donation</memo>
<check-number>1234</check-number>
<check-date>2009-04-24</check-date>
<cents type="integer">20000</cents>
<splits type="array">
<split>
<id type="integer">104573</id>
<donation-id type="integer">110172</donation-id>
<fund-id type="integer">10043</fund-id>
<cents type="integer">10000</cents>
<memo>A note about this split</memo>
<type>DonationSplit</type>
</split>
<split>
<id type="integer">104574</id>
<donation-id type="integer">110172</donation-id>
<fund-id type="integer">10003</fund-id>
<cents type="integer">10000</cents>
<memo nil="true"></memo>
<type>DonationSplit</type>
</split>
</splits>
</donation>
</pre>
<div><span style="color: #555555; font-size: 19px; font-weight: bold; ">POST: Create a Donation</span></div>
<h4>POST /donations.xml</h4>
<p><span style="line-height: normal;"> </span></p>
<pre><?xml version="1.0" encoding="UTF-8"?>
<donation>
<donation-type-id type="integer">1</donation-type-id>
<persona-id type="integer">121635</persona-id>
<new-split-attributes type="array">
<new-split-attribute>
<cents type="integer">1000</cents>
<fund-id type="integer">10043</fund-id>
</new-split-attribute>
</new-split-attributes>
<organization-id type="integer">10001</organization-id>
</donation>
</pre>
<div><span style="color: #555555; font-size: 19px; font-weight: bold; ">DELETE: Delete a Donation</span></div>
<h4>DELETE /donations/123.xml</h4>
2009-05-18T17:27:10-07:00
api
47417
285
36980
false
false
false
true
0
Ryan Heneise
54137
Donations API
2009-06-17T15:15:39-07:00