Record Donation Helper Version 2

This document describes the OSDI record donation helper endpoint as implemented by the Action Network.

The record donation helper allows you to create or update a person record and mark that person as having donated on a fundraising page at the same time (as well as tag that person).

This saves API calls. POSTing a new donation without the helper would mean you need a link to the person you want to associate the donation with, which would entail either an oData search to look up the existing person or a POST using the person_signup_helper to add the person first. The record donation helper allows you to post a person's data along with a donation, and the helper will automatically create or deduplicate the person and then create a donation for them on the specified fundraising page, all in one API call.

The record donation helper takes the normal donation format (described here) with an additional JSON hash with person data, and an optional array of tags to add to the person's record.

People are matched and deduplicated by email address. If a new person is created as part of a POST operation, that person will be subscribed to the email list associated with your API key. If the email address is found, that person's subscription status (subscribed, unsubscribed, etc...) will not be changed unless you pass subscribed in the status field, as described in the people documentation. In that case, the person will be subscribed to the list, even if they were previously unsubscribed. No other status fields are valid on this endpoint.

Items in the optional tags array are matched to existing tags associated with the list matching your API key by name. If a matching tag is found, that tag will be added to the person's record. If not, the tag will be ignored.

Finally, you can POST to this helper without an API key. This is useful to enable a javascript implementation, say the use of a custom form that you create, without leaking your API key to browsers. If you use unauthenticated or "blind" POST without an API key, the response will be essentially no information, to avoid leaking any personal data over the API without an API key present. You will receive a success status code and an empty JSON response if successful, or an error status code and an error message if not. See the blind post tutorial for an example.

Note: Donations are not deduplicated based on person, so a specific person can have more than one donation on a fundraising page. And unlike other action types, you may only post donations to fundraising pages that have been created via the API, and these will not send autoresponses or charge people money. You cannot add a donation to a fundraising page created using our user interface.

Sections:

Endpoint

Endpoint:

https://actionnetwork.org/api/v2/fundraising_pages/[fundraising_page_id]/donations

The record donation helper lives at the endpoint relating to the collection of donations on a specific fundraising page.

Back To Top ↑

Field names and descriptions

Record Donation Helper fields:
Field Name Type Required on POST Description
identifiers strings[] An array of identifiers in the format [system name]:[id]. Must be globally unique. See the general concepts document for more information about identifiers.
recipients Recipients[] Yes An array of hashes identifying the recipients of the donation. At least one recipient is required.
action_network:recurrence Recurrence A hash of details about the recurring nature of this donation. An Action Network-only feature.
action_network:referrer_data Referrer Data A hash of referrer data such as source code and referrer code. Action Network-only.
person Person* Yes A hash representing person data to associate with this donation. You can use any valid fields for person resources. An email address is required. See the people document for more information about people. (The person's language preference will be set to the language of the action as specified in the action's user interface.)
add_tags strings[] An array of strings representing tags to add to the person's record.
Recipient fields:
Field Name Type Required on POST Description
display_name string Yes The name of the recipient of this part of the donation.
amount string Yes The amount donated to this recipient.
Recurrence fields:
Field Name Type Required on POST Description
recurring boolean Indicates whether this is a recurring donation or not.
period enum Indicates the frequency with which this donation recurs. One of ["Weekly" "Monthly" "Quarterly" "Yearly"].
Referrer Data fields:
Field Name Type Required on POST Description
source string The source code of this donation. Equivalent to someone taking action with the url argument ?source=[your source]. Corresponds to the sources chart in this action's manage page. Action Network-only.
referrer string The referrer code of this donation. Equivalent to someone taking action with the url argument ?referrer=[your referrer code]. Must be a valid Action Network referrer code. Read-only. Corresponds to the referrers chart in this action's manage page. Action Network-only.
website string The website referrer for this donation. Equivalent to someone taking action after clicking a link on the listed website. Corresponds to the websites chart in this action's manage page. Action Network-only.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Creating a new donation (POST)

If you post with an inline person hash instead of with a link to a person object as described here, we will create or update the matching person and associate them with a new donation on the specified fundraising page, all in one API call.

An email address is the only required field, though others can be POSTed.

People are matched and deduplicated by email address. If a new person is created as part of a POST operation, that person will be subscribed to the email list associated with your API key. If the email address is found, that person's subscription status (subscribed, unsubscribed, etc...) will not be changed unless you pass subscribed in the status field, as described in the people documentation. In that case, the person will be subscribed to the list, even if they were previously unsubscribed. No other status fields are valid on this endpoint.

Either way, donations are not deduplicated by person, so a person can donate to a fundraising page more than once.

Tags can also be added to a person's record when POSTing using the helper by including the optional tags array. Items in the array are matched to existing tags associated with the list matching your API key by name. If a matching tag is found, that tag will be added to the person's record. If not, the tag will be ignored.

Finally, you can POST to this helper without an API key. This is useful to enable a javascript implementation, say the use of a custom form that you create, without leaking your API key to browsers. See the blind post tutorial for an example.

Note: Unlike other action types, you may only post donations to fundraising pages that have been created via the API, and these will not send autoresponses or charge people money. You cannot add a donation to a fundraising page created using our user interface.

Here is an example of posting a donation with person data inlined to the special record_donation_helper link on the donations collection, along with tags:

Request

						
POST https://actionnetwork.org/api/v2/fundraising_pages/f77e736b-d295-4e68-96ec-a765090c6523/donations

Header:
Content-Type: application/json
OSDI-API-Token: your_api_key_here
						

{
  "identifiers": [
    "free_fundraisers:2"
  ],
  "recipients": [
    {
      "display_name": "Campaign To Elect Tom",
      "amount": "3.00"
    }
  ],
  "person" : {
    "family_name" : "Smith",
    "given_name" : "John",
    "postal_addresses" : [ { "postal_code" : "20009" }],
    "email_addresses" : [ { "address" : "jsmith@mail.com" }]
  },
  "add_tags": [
    "donor",
    "member"
  ]
} 
					

Response

						
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate


{
  "identifiers": [
    "free_fundraisers:2",
    "action_network:38ec0365-f996-42a0-b26a-dbed24cf927f"
  ],
  "created_date": "2014-03-27T17:58:45Z",
  "modified_date": "2014-03-27T17:58:45Z",
  "currency": "USD",
  "amount": "3.00",
  "recipients": [
    {
      "display_name": "Campaign To Elect Tom",
      "amount": "3.00"
    }
  ],
  "payment": {
    "method": "Credit Card",
    "reference_number": "38ec0365-f996-42a0-b26a-dbed24cf927f",
    "authorization_stored": false
  },
  "action_network:recurrence": {
    "recurring": false
  },
  "action_network:person_id": "17be9a36-bb9a-4f68-94a8-40523b9dab27",
  "action_network:fundraising_page_id": "f77e736b-d295-4e68-96ec-a765090c6523",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/fundraising_pages/f77e736b-d295-4e68-96ec-a765090c6523/donations/38ec0365-f996-42a0-b26a-dbed24cf927f"
    },
    "osdi:fundraising_page": {
      "href": "https://actionnetwork.org/api/v2/fundraising_pages/f77e736b-d295-4e68-96ec-a765090c6523"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/17be9a36-bb9a-4f68-94a8-40523b9dab27"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
					

In the above example, a new person was created and their donation added to the fundraising page at the same time. The tags "donor" and "member" were added to that person's record as well. We deduplicate people added this way by email address, so if the email posted corresponded with a person already in the system, we would update their record instead of creating a new person. The required fields for person remain the same -- email address and postal code -- and any posts missing that information will fail.

If the person is new, they will be subscribed to the list associated with your API key. If not, their subscription status (subscribed, unsubscribed, etc...) will not be changed unless you pass subscribed in the status field, as described in the people documentation. In that case, they will be subscribed to the list, even if they were previously unsubscribed. No other status fields are valid on this endpoint.

Of course you can POST a donation with more fields such as address lines for your inline person data or custom fields if you'd like, but they are not required. And you can omit your API key, in which case the response will a success status code and an empty JSON object if successful, or an error code and message if not.

Back To Top ↑