Donations Version 2

This document describes the OSDI donations collection and donation resource as implemented by the Action Network.

Donations represent the action an activist took when they donated on a specific fundraising page.

Donations have recipients indicating who the money went to, and are linked to the person resource corresponding to the activist who made the donation.

Note: Donations are not deduplicated based on person, unlike other similar resources in the Action Network API, so a specific person can donate more than once 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:

Endpoints and URL structures

Endpoints:

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

https://actionnetwork.org/api/v2/people/[person_id]/donations

https://actionnetwork.org/api/v2/donations

Donation resources live at endpoints relating to the person who donated and the fundraising page they donated on, as well as the top level API entry point. The endpoints return a collection of all donations associated with either that person or that fundraising page, or all donations associated with your API key.

URL Structures:

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

https://actionnetwork.org/api/v2/people/[person_id]/donations/[donation_id]

https://actionnetwork.org/api/v2/donations/[donation_id]

To address a specific donation, use the identifier without the action_network: prefix to construct a URL, like https://actionnetwork.org/api/v2/fundraising_pages/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/donations/167ce1d2-70b7-423e-b480-914981cbeaff

Back To Top ↑

Field names and descriptions

Donation 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.
created_date datetime The date and time the resource was created. POSTing a date allows for backdating of donations.
modified_date datetime The date and time the resource was last modified. System generated, not editable.
amount string A system generated count of the amount of money for this donation. Not editable.
currency string ISO 4217 designation of currency. System generated, not editable.
recipients Recipients[] Yes An array of hashes identifying the recipients of the donation. At least one recipient is required.
payment Payment A hash of payment information about this donation for reporting purposes.
action_network:recurrence Recurrence A hash of details about the recurring nature of this donation. An Action Network-only feature.
action_network:person_id string The native Action Network identifier associated with the person who donated. Action Network-only feature. System generated, not editable.
action_network:fundraising_page_id string The native Action Network identifier associated with the fundraising page this donation was made on. Action Network-only feature. System generated, not editable.
action_network:referrer_data Referrer Data A hash of referrer data such as source code and referrer code. Action Network-only.
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. Will be added together with other recipient amounts to come up with the amount field above.
Payment fields:
Field Name Type Required on POST Description
method enum The method of payment. One of ['Credit Card' 'Check' 'Cash' 'Electronic Funds Transfer']. System generated, always Credit Card, not editable.
reference_number string A check number, transaction ID, or some other information referencing the payment. System generated, not editable.
authorization_stored boolean Indicates if payment information has been stored for future automatic payments. System generated, not editable.
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' 'Every 3 Months' '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. Action Network-only.
email_referrer string The id of the email that brought someone to the link to take action. Action Networks adds the ?email_referrer=[your email referrer] URL parameter on the links sent through the emailer. Pass that value back in your API calls here to mark this action as having taken place because of a response to that email.
mobile_message_referrer string The id of the mobile message that brought someone to the link to take action. Action Networks adds the ?mobile_message_referrer=[your mobile referrer] URL parameter on the links sent through mobile messages. Pass that value back in your API calls here to mark this action as having taken place because of a response to that message.
Back To Top ↑

Links

Link Name Description
self A link to this individual donation resource.
osdi:person A link to the person who made this donation. Click here for people documentation.
osdi:fundraising_page A link to the fundraising page this donation was left on. Note: If this donation was created via a referral code, this link may not be accessible because your API key does not give you permission to access the fundraising page itself. Click here for fundraising page documentation.
Back To Top ↑

Related resources

Back To Top ↑

Scenario: Retrieving a collection of donation resources (GET)

Donation resources are sometimes presented as collections of donations. For example, calling the donations endpoint on a specific fundraising page will return a collection of all the donations associated with that fundraising page.

Request

						
GET https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations

Header:
OSDI-API-Token: your_api_key_here

Response

						
200 OK

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


{
  "total_pages": 1,
  "per_page": 25,
  "page": 1,
  "total_records": 6,
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations"
    },
    "osdi:donations": [
      {
        "href": "https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
      },
      {
        "href": "https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/d86538c1-e8f7-46e1-8320-552da81bd48d"
      },
      //truncated for brevity
    ],
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  },
  "_embedded": {
    "osdi:donations": [
      {
        "identifiers": [
          "action_network:f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
        ],
        "created_date": "2014-03-27T17:42:21Z",
        "modified_date": "2014-03-27T17:42:24Z",
        "currency": "USD",
        "amount": "20.01",
        "recipients": [
          {
            "display_name": "John Doe",
            "amount": "6.67"
          },
          {
            "display_name": "Progressive Action Now",
            "amount": "6.67"
          },
          {
            "display_name": "Jane Black",
            "amount": "6.67"
          }
        ],
        "payment": {
          "method": "Credit Card",
          "reference_number": "f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16",
          "authorization_stored": false
        },
        "action_network:recurrence": {
          "recurring": true,
          "period": "Monthly"
        },
        "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
        "action_network:fundraising_page_id": "049e9bda-cb79-420d-91ba-92e5a15ba62f",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
          },
          "osdi:fundraising_page": {
            "href": "https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          }
        }
      },
      {
        "identifiers": [
          "action_network:d86538c1-e8f7-46e1-8320-552da81bd48d"
        ],
        "created_date": "2014-03-27T17:40:56Z",
        "modified_date": "2014-03-27T17:41:11Z",
        "currency": "USD",
        "amount": "20.00",
        "recipients": [
          {
            "display_name": "John Doe",
            "amount": "10.00"
          },
          {
            "display_name": "Progressive Action Now",
            "amount": "10.00"
          }
        ],
        "payment": {
          "method": "Credit Card",
          "reference_number": "d86538c1-e8f7-46e1-8320-552da81bd48d",
          "authorization_stored": false
        },
        "action_network:recurrence": {
          "recurring": false
        },
        "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
        "action_network:fundraising_page_id": "049e9bda-cb79-420d-91ba-92e5a15ba62f",
        "_links": {
          "self": {
            "href": "https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/d86538c1-e8f7-46e1-8320-552da81bd48d"
          },
          "osdi:fundraising_page": {
            "href": "https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f"
          },
          "osdi:person": {
            "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
          }
        }
      },
      //truncated for brevity
    ]
  }
}
Back To Top ↑

Scenario: Retrieving an individual donation resource (GET)

Calling an individual donation resource will return the resource directly, along with all associated fields and appropriate links to additional information about the donation.

Request

						
GET https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16

Header:
OSDI-API-Token: your_api_key_here

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
  ],
  "created_date": "2014-03-27T17:42:21Z",
  "modified_date": "2014-03-27T17:42:24Z",
  "currency": "USD",
  "amount": "20.01",
  "recipients": [
    {
      "display_name": "John Doe",
      "amount": "6.67"
    },
    {
      "display_name": "Progressive Action Now",
      "amount": "6.67"
    },
    {
      "display_name": "Jane Black",
      "amount": "6.67"
    }
  ],
  "payment": {
    "method": "Credit Card",
    "reference_number": "f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16",
    "authorization_stored": false
  },
  "action_network:recurrence": {
    "recurring": true,
    "period": "Monthly"
  },
  "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
  "action_network:fundraising_page_id": "049e9bda-cb79-420d-91ba-92e5a15ba62f",
  "_links": {
    "self": {
      "href": "https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f/donations/f1119c4e-b8ca-44ff-bfa7-f78f7ca3ec16"
    },
    "osdi:fundraising_page": {
      "href": "https://actionnetwork.org/api/v2/fundraising_pages/049e9bda-cb79-420d-91ba-92e5a15ba62f"
    },
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}
Back To Top ↑

Scenario: Creating a new donation (POST)

You can post a new donation to a fundraising page with that fundraising page's donations endpoint and a donation resource will be created in our system.

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.

When you post a donation, you can either link to an existing person to register that this person donated on this fundraising page, or you can post information about a new person inline to the special record_donation_helper endpoint, to both create a new person and register that they donated on this fundraising page at the same time. You can learn more about the record donation helper here.

Unlike other similar resources, donations are not deduplicated by person. A person may donate to a fundraising page more than once. Posting a new donation by a person who previously donated will create a new donation resource.

Background processing is available on this operation via the background_request=true URL argument. You can learn more about background processing here.

Here is an example of posting a donation linking to an existing person:

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


{
  "recipients": [
    {
      "display_name": "Campaign To Elect Tom",
      "amount": "3.00"
    }
  ],
  "created_date": "2013-01-01T00:00:00Z",
  "_links" : {
    "osdi:person" : { "href" : "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29" }
  }
}

Response

						
200 OK

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


{
  "identifiers": [
    "action_network:c2f42b7b-8d86-4afd-ba7e-d7b5b74abfc5"
  ],
  "created_date": "2013-01-01T00:00:00Z",
  "modified_date": "2014-03-27T17:57:02Z",
  "currency": "USD",
  "amount": "3.00",
  "recipients": [
    {
      "display_name": "Campaign To Elect Tom",
      "amount": "3.00"
    }
  ],
  "payment": {
    "method": "Credit Card",
    "reference_number": "c2f42b7b-8d86-4afd-ba7e-d7b5b74abfc5",
    "authorization_stored": false
  },
  "action_network:recurrence": {
    "recurring": false
  },
  "action_network:person_id": "c945d6fe-929e-11e3-a2e9-12313d316c29",
  "action_network:fundraising_page_id": "f77e736b-d295-4e68-96ec-a765090c6523",
  "_links": {
    "osdi:person": {
      "href": "https://actionnetwork.org/api/v2/people/c945d6fe-929e-11e3-a2e9-12313d316c29"
    },
    "self": {
      "href": "https://actionnetwork.org/api/v2/fundraising_pages/f77e736b-d295-4e68-96ec-a765090c6523/donations/c2f42b7b-8d86-4afd-ba7e-d7b5b74abfc5"
    },
    "osdi:fundraising_page": {
      "href": "https://actionnetwork.org/api/v2/fundraising_pages/f77e736b-d295-4e68-96ec-a765090c6523"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      },
      {
        "name": "action_network",
        "href": "https://actionnetwork.org/docs/v2/{rel}",
        "templated": true
      }
    ]
  }
}

And of course you can post a donation with more fields (such as referrer data) if you'd like, but they are not required.

Back To Top ↑

Scenario: Modifying or deleting a donation (PUT/DELETE)

Modifying or deleting donations is not allowed via the API, requests will return an error.

Back To Top ↑