Person Data Structure

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

Request

Response

<?xml version="1.0" encoding="UTF-8"?>
<persona>
  <birth-date type="date" nil="true"></birth-date>
  <company-name nil="true"></company-name>
  <created-at type="datetime" nil="true"></created-at>
  <deceased type="boolean">false</deceased>
  <department nil="true"></department>
  <gender type="integer" nil="true"></gender>
  <is-company type="boolean">false</is-company>
  <job-title nil="true"></job-title>
  <legacy-id nil="true"></legacy-id>
  <meta type="yaml" nil="true"></meta>
  <recognition-name nil="true"></recognition-name>
  <salutation nil="true"></salutation>
  <salutation-formal nil="true"></salutation-formal>
  <tag-list nil="true"></tag-list>
  <updated-at type="datetime" nil="true"></updated-at>
  <names type="array">
    <name>
      <first-name nil="true"></first-name>
      <last-name nil="true"></last-name>
      <middle-name nil="true"></middle-name>
      <name-type-id type="integer" nil="true"></name-type-id>
      <position type="integer" nil="true"></position>
      <prefix nil="true"></prefix>
      <suffix nil="true"></suffix>
    </name>
  </names>
  <addresses type="array">
    <address>
      <city nil="true"></city>
      <country nil="true"></country>
      <do-not-mail type="boolean">false</do-not-mail>
      <position type="integer" nil="true"></position>
      <postal-code nil="true"></postal-code>
      <state nil="true"></state>
      <street-address nil="true"></street-address>
      <time-zone nil="true"></time-zone>
    </address>
  </addresses>
  <phone-numbers type="array">
    <phone-number>
      <address-type-id type="integer" nil="true"></address-type-id>
      <do-not-call type="boolean">false</do-not-call>
      <extension nil="true"></extension>
      <phone-number nil="true"></phone-number>
      <position type="integer" nil="true"></position>
    </phone-number>
  </phone-numbers>
  <email-addresses type="array">
    <email-address>
      <address-type-id type="integer" nil="true"></address-type-id>
      <do-not-email type="boolean">false</do-not-email>
      <email-address nil="true"></email-address>
      <position type="integer" nil="true"></position>
    </email-address>
  </email-addresses>
  <web-addresses type="array">
    <web-address>
      <address-type-id type="integer" nil="true"></address-type-id>
      <position type="integer" nil="true"></position>
      <web-address nil="true"></web-address>
    </web-address>
  </web-addresses>
  <twitter-usernames type="array">
    <twitter-username>
      <address-type-id type="integer" nil="true"></address-type-id>
      <position type="integer" nil="true"></position>
      <twitter-username nil="true"></twitter-username>
    </twitter-username>
  </twitter-usernames>
</persona>

Listing People

Request

Response

<personas type="array" current_page="1" per_page="20" total_entries="673">
  <persona>
    ...
  </persona>
</people>

Pagination & Sorting

Donor Tools uses a standard pagination scheme for paginating People. You can sort people by passing the "order" parameter - for example -"people.(xml|json)?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. 

Request

GET /people.(xml|json)?order=email_address&direction=DESC

Supported Sorting Columns

• name
• address
• donations
• most_recent_donation
• email_address
• company
• added
• last_activity

Get a Specified Person by Id

Request

Response

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

Create a Person

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

Request

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

Response

Tagging

You can tag a donor by passing an element called "tag-list". This can either be an array or a comma-separated list.

<persona>
  ...
  <tag-list type="array">
    <tag-list>Tag 1</tag-list>
    <tag-list>Tag 2</tag-list>
  </tag-list>
</persona>

<persona>
  ...
  <tag-list>Tag 1, Tag 2</tag-list>
</persona>

Update

To make sure that you have the most recent data for a Person resource, it is usually a good idea to GET the persona 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"?>
<persona>
  ...
</persona>

Response

Delete a Person

Deleting a persona cascades to all the persona's objects: donations, notes, names, relationships, etc. will all be deleted when a persona is deleted. There is no confirmation before deleting, so be sure you are sure before passing the DELETE method!

Request

Response